附录：术语表与 ADR 索引
2026.07.29A. 术语表
| 中文 | English | 简要说明 |
|---|---|---|
| Agent | Agent | 基于 LLM 驱动、能自主调用工具完成任务的软件实体 |
| 身份声明 | Identity Statement | AGENTS.md 中定义 agent 角色和原则的文件，作为 system prompt 的源头 |
| 文件系统即自我 | Filesystem as Self | CodeCoder 核心原则：agent 的身份、知识、能力由磁盘上的文件定义而非硬编码 |
| 工具 | Tool | 编译进二进制的原生原语，运行时不可增删（共 26 个） |
| 技能 | Skill | 以 .md 文件存储的程序性知识，改变 agent 的推理路径 |
| 草稿 | Prompt/Draft | Skill 的草稿态，存放在 prompts/，可晋升为 Skill |
| 能力 | Capability | agent 自撰的可执行产物，附 manifest 声明环境和生命周期 |
| 环境 | Environment | Capability 的执行后端：Shell / Wasm / Docker |
| 生命周期 | Lifecycle | Capability 的运行模式：OneShot（一次性）/ OnDemand（按需）/ Persistent（常驻） |
| 权限键 | Permission Key | 细粒度权限标识，格式如 run_command:git |
| 会话白名单 | Session Allowlist | 运行期内存的权限缓存，session 结束时清除 |
| 项目白名单 | Project Allowlist | 持久化在 codecoder.json 中的权限配置，跨 session 生效 |
| 天花板规则 | Ceiling Rule | @shell 环境最高只能授予 AlwaysThisSession 信任级别 |
| 静默降级 | Silent Degradation | 环境不可用时自动落到更低安全级别运行——CodeCoder 禁止此行为 |
| turn | Turn | agent 从接收用户消息到自主决定输出完成的完整处理周期 |
| 命令通道 | Command Channel (cmd_tx) | 传递用户主动意图的通道 |
| 事件通道 | Event Channel (event_rx) | 传递流式增量和结构化状态的通道 |
| 协作式取消 | Cooperative Cancellation | 通过共享 CancelToken 优雅终止 agent 操作，而非强杀线程 |
| 子代理 | Sub-agent | 通过 agent 工具创建的只读子实例，深度锁定为 1 |
| 只读工具集 | Read-only Toolset | 子 agent 可用的 9 个只读工具 |
| 工作图 | Work Graph | 事前构造的里程碑依赖图（DAG） |
| 会话 | Session | 事后记录的消息树（JSON 格式），事实载体 |
| 里程碑 | Milestone | 工作图中的单个节点，有状态和依赖 |
| 验收门 | Acceptance Gate | 里程碑完成的验证层级 |
| 命令门 | Command Gate | 第一级验收：agent 自报完成 |
| 检查门 | Check Gate | 第二级验收：确定性自动化检查（编译、模板、文件数等） |
| 审查门 | Review Gate | 第三级验收：独立只读子 agent 的结构化架构评审 |
| 自恢复循环 | Self-recovery Loop | needs_fix 状态下有界自动重试 |
| 无用户模式 | Headless Mode | 无用户在场的自主运行模式 |
| 预授权 | Pre-authorization | codecoder.json 中的权限配置 |
| 熔断 | Circuit Breaking | 连续失败 K 次后主动终止 |
| 上下文压缩 | Compaction | 两级压缩策略：tier-1 丢弃 + 占位化，tier-2 结构化摘要 |
| 持久化 | Persistence | Session 文件的 JSON 格式与迁移链 |
| 结构化摘要 | Structured Summary | tier-2 压缩的五个字段摘要模板 |
| 可观测性 | Observability | 事件流、NDJSON 实时日志、结构化追踪 |
| 常驻目录 | Registry | 启动时扫描 skills/、prompts/、capabilities/ 形成的文件索引表 |
| 持久化记忆 | Memory | agent 主动写入的 key-value 记忆，跨 session 共享 |
| 离线单元测试 | L1 Test | 无 LLM 调用的单元测试 |
| 黑盒行为验证 | L2 Test | 使用 ScriptedProvider 的行为测试 |
| 真实 LLM 冒烟 | L3 Test | 连接真实 LLM 的端到端测试 |
B. ADR 索引
CodeCoder 的完整架构决策记录存放于 docs/adr/ 目录，共 31 份（数据采集时间：2026 年 7 月 28 日）。
| ADR | 标题 | 对应章节 |
|---|---|---|
| 0015 | Unified Message Model | 第 1 编第 1 章、第 2 编第 1 章 |
| 0016 | Channel Topology and Event Model | 第 1 编第 1 章、第 2 编第 1 章 |
| 0017 | Provider Neutral Message Model | 第 1 编第 1 章、第 2 编第 1 章 |
| 0018 | Tool Trait and Permission Keys | 第 2 编第 2 章 |
| 0019 | Sub-agent Capability Boundary | 第 2 编第 3 章 |
| 0020 | Skills and Capabilities Registry | 第 3 编第 1、2 章 |
| 0021 | Capability Environments and Lifecycle | 第 3 编第 3 章 |
| 0022 | Self-authoring Safety Loop | 第 3 编第 4 章 |
| 0023 | Context Compaction | 第 4 编第 4 章 |
| 0025 | Prompt as Skill Draft Tier | 第 3 编第 1、2 章 |
| 0026 | Background Agent Headless Runner | 第 4 编第 3 章 |
| 0030 | BG Objective Acceptance Gate | 第 4 编第 2 章 |
| 0032 | Client-Server Architecture | 第 5 编第 1 章 |
| 0033 | BG Ledger and Exit Codes | 第 4 编第 3 章 |
| 0034 | Persistent Supervisor Cross-restart | 第 3 编第 3 章、第 4 编第 3 章 |
| 0036 | Compound Command Keying | 第 2 编第 2 章 |
| 0039 | BG Review Gate and Observability | 第 4 编第 2 章、第 5 编第 2 章 |
C. 项目数据页
数据采集时间：2026 年 7 月 28 日
| 指标 | 数值 |
|---|---|
| 源文件 | 31 个（src/ 下 24 个 + daemon/ + client/） |
| 测试文件 | 13 个 |
| 测试用例 | 481 个（含 1 个 #[ignore]） |
| 内置工具 | 26 个 |
| 技能 (Skill) | 6 个 |
| 能力 (Capability) | 1 个 |
| 架构决策记录 (ADR) | 31 份 |
| 编程语言 | Rust |
| LLM 协议 | OpenAI 兼容（Provider 中立） |
| 运行模式 | 交互式（TUI / Socket）和 Headless（环境变量触发） |
| 通信协议 | Unix socket，daemon-client 架构 |
注：术语表中的英文术语在正文中以英文形式出现，首次出现时括号内标注中文。