ai-context-framework

一个模型无关的 AI 上下文管理框架模板。

当前推荐版本

v0.0.3.73 是当前推荐版本。它继承 .72 的 sufficient scheduler bootstrap、state-conditioned generated prompt、default execution plan、owner liveness/duplicate-wake 语义和 continuation capacity/effect rollover hardening，并补上一条窄的 legacy local-effect recovery：旧版本若留下 prepared + external_id=null 的本地确定性 effect，且 owner 已结束/forfeit、durable local authority evidence 已能证明实际 terminal 结果，可显式使用 reconcile --effect-local-terminal 收口；该路径不适用于 active/unknown effect，也不能绕过已有 external-id 的 identity-matched reconciliation。ACF 仍不会从文件名或普通项目事实自动裁决 effect 真假，调用方必须提供可审计 evidence，recover 仍受 observation digest、receipt 与 generation fencing 约束。

• 版本变化：CHANGELOG.md
• Workstream/Worktree 教程：docs/Worktree_Lifecycle.md
• 详细 CLI 参数：acf --help、acf workstream reserve --help、acf worktree --help、acf continuation --help

ACF 的默认 AI 入口采用 global-first progressive disclosure：无论项目有一个还是多个 Active / Blocked / ReadyToMerge / Merging Workstream，只要没有明确选择，agent 都只读取全局上下文和 Workstreams 摘要，不读取任何 WS detail、read_scope、reference、output 或专属 worklog。显式选择后，acf status|next --workstream WSNNN 仍只返回 pointer-only 入口；随后调用 acf workstream context WSNNN 才披露专属上下文和边界。reference/ 是项目内中间材料层，Knowledge 是有来源、证据和适用边界的高可信精炼层，均按需读取。

acf check --strict 只能证明结构、断链、状态和索引一致性；不能证明项目事实完全正确。升级后仍需人工或 AI 审查 Context.md、Project_Brief.md、Tech_Context.md、AGENTS.md 和项目特有规则是否准确。

稳定入口和开发入口需要分开：真实项目中使用非 editable 安装的稳定 acf；在本仓库开发时使用 uv run acf 或 uv run python acf.py。只有在调试安装链路或 CLI 改动时，才临时使用 editable install。

设计理念

人与 AI 的协作中，人作为最高决策层，AI 同时作为执行者和策略建议者。项目知识不应随 AI 工具更换或人员离开而丢失。

本框架通过分层的 Markdown 文件结构管理项目上下文，实现：

• 模型无关：纯 Markdown，不依赖任何 AI 工具的私有格式
• 渐进式暴露：AI 默认只读取当前有效上下文，按需读取历史和参考资料
• 单一事实源：每类信息有唯一的权威位置，避免重复维护和冲突
• 注意力治理：默认注意力入口只保留低噪声、高权威、任务相关的信息
• 决策可追溯：通过 ADR（Architecture Decision Record）记录重要决策的完整推理过程

目录结构

template/
  AGENTS.md              # AI 入口文件（~115 行）
  active/                # 当前有效上下文（AI 默认读取）
    Context.md           # 当前阶段目标、事实、约束
    Feedback_Inbox.md    # 人工反馈、问题、需求和计划碎片
    Task_Plan.md         # 当前大任务计划、规划依据、轻量子任务板和可选任务阶段表
    Current_Task.md      # 当前具体小任务，可记录当前执行 Workstream
  human/                 # 人类给 AI 的半结构化材料层（默认不读，按需读取）
    Human_Index.md       # human 材料索引和处理状态
    Human_Notes.md       # 人工随笔、疑问、规划草稿 inbox
    weekly/              # 周记录
    reports/             # 复盘、解释、整理和汇报材料
  rules/                 # 规则系统（分层加载）
    Always_Active.md     # 每次必须遵守的核心规则
    Project_Rules.md     # 项目级通用规则
    Coding_Rules.md      # 代码任务规则
    Writing_Rules.md     # 写作任务规则
    Review_Rules.md      # 评审任务规则
    ...
  reference/             # 支持性资料（按需读取）
    Project_Brief.md     # 长期目标和愿景
    Architecture.md      # 架构说明
    Tech_Context.md      # 技术环境
    Decisions_Index.md   # 决策索引
    Knowledge_Index.md   # 可复用经验索引
    Context_Curation_Prompt.md # 按需上下文整理 prompt
    Sources_Index.md     # 外部资料索引
    System_Manual.md     # 系统详细使用手册
  decisions/             # ADR 决策记录
  worklog/               # 工作日志
  archive/               # 历史归档
    feedback/            # 已处理反馈归档

使用方法

1. 安装 CLI 后，在项目根目录运行 acf init docs/ai
2. init 会在项目根目录生成薄入口 AGENTS.md，在 docs/ai/ 下生成完整入口 AGENTS.md
3. 根据项目需要填充模板中的占位符
4. AI 进入项目时，从根目录 AGENTS.md 开始读取

关于两层 AGENTS.md 的设计

这是"渐进式暴露"原则的实践：

层级	文件	内容	维护者	频率
第一层	./AGENTS.md	薄入口 + 仓库级约定	框架维护者	很少改
第二层	docs/ai/AGENTS.md	完整上下文导航	项目团队 + AI	按阶段更新

目的是在不暴露过多细节的前提下，让 AI 能逐步了解项目上下文结构。

如果项目根目录已经存在 AGENTS.md，init 默认不会覆盖；确认要重写根薄入口时再传入 --force-root-agent。

信息层级

层级	目录	读取时机	说明
1	active/	默认读取	当前阶段事实、人工反馈 inbox、当前大任务计划和当前小任务
2	human/	按需	人类给 AI 的理解、规划、疑问、解释、随笔、复盘和汇报材料
3	rules/	Always_Active 默认，其余按需	行为规则
4	reference/	按需	背景资料、知识和索引
5	decisions/	按需	决策详情
6	worklog/	按需	工作历史
7	archive/	仅明确要求时	归档内容

事实源优先级

冲突时按以下顺序判断：

1. 用户当前消息
2. Current_Task.md
3. Task_Plan.md
4. Context.md
5. Feedback_Inbox.md（只作为待整理信号，不作为已确认事实）
6. human/（只作为人工未整理笔记或汇报材料，不作为已确认事实）
7. Decisions_Index.md
8. ADR 文件
9. Knowledge_Index.md
10. worklog
11. archive

人工笔记与 Obsidian

标准 profile 会生成 docs/ai/human/，用于人类给 AI 上下文系统留下的主观、半结构化材料，包括理解、规划、疑问、解释、整理、随笔、复盘和汇报。它默认不进入 AI 注意力，只在用户要求整理/修改 human 内容、当前任务显式引用 human 材料，或需要追溯人工判断来源时按需读取；需要成为当前事实的内容，应整理到 active/、ADR、Knowledge、reference 或 worklog 的权威位置。

human/Human_Index.md 是 human 层的可发现索引；acf human index sync 会扫描 Human_Notes.md、weekly/*.md 和 reports/*.md 并补齐缺失索引行。工具只做机械索引维护，Reviewed / Extracted / Archived 等语义状态需要人或 AI 在整理后显式标记。

可以把项目 docs/ 作为 Obsidian vault 根目录，用 [[双链]] 连接 docs/ai/ 和其他项目文档。双链只服务人工查看和编辑；ACF 不解析、不校验、不依赖 Obsidian 双链，CLI 结构化引用仍使用普通 Markdown 路径。

ACF 结构化引用优先使用普通 Markdown 链接，例如 [reference/System_Manual.md](../reference/System_Manual.md)。acf check 会校验上下文内本地 Markdown 链接和图片链接的文件是否存在，并校验 .md#anchor 能匹配目标文件标题；URL 和其他 URI scheme 不做网络校验。需要批量转换时使用 acf linkify [target] --format markdown --dry-run --json；需要向指定小节追加确定性链接时使用 acf link add [target] <file> --heading "## 输入材料" --target reference/X.md --json。

注意力治理

ACF 不追求保存更多上下文，而是维护一个低噪声、高权威、任务相关的默认注意力入口。

• active/ 只保留当前目标、当前事实、当前任务和下一步。
• 写入当前事实前先判断唯一权威位置；能更新旧表述时，不追加重复事实。
• worklog 记录历史过程，archive 保存历史材料，Feedback_Inbox 和 human 保存待处理或未整理信号；它们默认不作为当前事实。
• 整理事实时优先读取 changed files、active/、相关索引和最近 worklog，不默认读取 archive 或全部历史日志。
• writeback draft 和 curation draft 不进入默认读取路径；能引用权威位置时，不复制完整表述。

命令行工具

本仓库提供一个无第三方依赖的辅助 CLI：

安装到 PATH

acf 已经通过 pyproject.toml 暴露为标准 console script。Windows 和 WSL/Linux 是两套独立环境：在哪个环境里运行 acf，就需要在哪个环境里安装一次。

• 正式用户安装发布版本：uv tool install ai-context-framework
• 已安装发布版本后一键更新：uv tool upgrade ai-context-framework
• 安装或更新后刷新 shell PATH：uv tool update-shell
• 仓库维护者安装当前源码快照：uv tool install .
• 开发安装（仅调试 CLI 修改时使用）：uv tool install -e .

Windows PowerShell

正式发布版本安装（推荐）：

uv tool install ai-context-framework
uv tool update-shell

正式发布版本更新：

uv tool upgrade ai-context-framework
uv tool update-shell

如果已经取得本仓库源码，也可以使用一键脚本：

pwsh -NoLogo -NoProfile -File scripts/install_acf.ps1
pwsh -NoLogo -NoProfile -File scripts/update_acf.ps1

开发安装（仅仓库维护或调试安装链路时使用）：

uv tool install -e .
uv tool update-shell

重新打开 PowerShell 后验证：

Get-Command acf
acf --help
acf --version
acf status --json

Windows CMD 可用 where.exe acf 查看命令位置。

WSL / Linux / macOS

正式发布版本安装（推荐）：

uv tool install ai-context-framework
uv tool update-shell

正式发布版本更新：

uv tool upgrade ai-context-framework
uv tool update-shell

如果已经取得本仓库源码，也可以使用一键脚本：

sh scripts/install_acf.sh
sh scripts/update_acf.sh

开发安装（仅仓库维护或调试安装链路时使用）：

uv tool install -e .
uv tool update-shell

重新打开 shell，或按 uv tool update-shell 的提示刷新 PATH 后验证：

which acf
acf --help
acf --version
acf status --json

如果 WSL 项目目录位于 /mnt/* 挂载盘，uv 可能提示 hardlink 失败并降级为 copy；这是跨文件系统性能提示，不影响安装。需要消除提示时可设置 export UV_LINK_MODE=copy。

如果需要把 CLI 装进当前 Python 环境而不是 uv tool 工具目录，也可以使用 python -m pip install .。Git URL 只适合临时测试；正式用户应从 PyPI 安装，以便 uv tool upgrade ai-context-framework 能从发布源获取新版本。

“任意目录可运行 acf”表示命令已进入 PATH；是否能自动找到上下文，取决于当前目录是否位于包含 docs/ai、docs-acf/ai 或上下文根目录的项目中。

常用命令

acf status
acf init docs/ai
acf init docs/ai-min --profile minimal
acf simplify docs/ai docs/ai-min
acf upgrade --dry-run --json
acf plan init --title "跨项目评测" --goal "完成一轮完整路径验证。"
acf plan add-task --title "验证 init/status/check" --output "命令结果摘要" --next-action "运行命令并记录结果"
acf task start --id T001
acf task done --id T001 --evidence "worklog/daily/YYYY-MM-DD.md"
acf archive current-task --reason "任务已完成"
acf knowledge draft --title "任务拆分经验" --source "worklog/daily/YYYY-MM-DD.md"
acf knowledge apply worklog/knowledge-drafts/YYYY-MM-DD-task.md --allow-similar
acf review stale --json
acf audit context --json
acf doctor --json
acf doctor --fix safe --dry-run --json
acf doctor --report --today YYYY-MM-DD --json
acf doctor --draft-semantic --today YYYY-MM-DD --json
acf doctor --projects ../project-a/docs/ai ../project-b/docs/ai --json
acf curate draft --dry-run --json
acf workstream status --json
acf workstream init --dry-run --json
acf workstream add --id WS002 --title "并行线" --owner "主 agent" --goal "验证并行目标线。" --output "验证记录"
acf workstream add --id WS003 --type Merge --title "合并线" --owner "主 agent" --goal "合并 ReadyToMerge 产物。" --output "合并记录"
acf workstream set WS002 --goal "补充或替换目标。"
acf workstream set WS002 --status Active
acf workstream context WS002
acf workstream scope-add WS002 --write "owned: src/foo.py" --reason "需要修改实现文件。"
acf workstream guard WS002 --files src/foo.py docs/ai/active/workstreams/WS002.md --json
acf workstream dashboard
acf workstream merge-request WS002 --target Context --summary "候选变更摘要" --verification "测试通过"
acf workstream ready WS002 --human-approved
acf workstream merge-start WS003
acf workstream done WS002 --evidence "worklog/daily/YYYY-MM-DD.md" --merge-resolution merged
acf workstream claim WS002 --read reference/Architecture.md --write "assigned: src/foo.py"
acf workstream note WS002 --section 当前发现 --text "记录一个局部发现。"
acf workstream stage add WS002 --id WS002.1 --title "内部阶段"
acf workstream stage list WS002 --json
acf workstream focus WS002 WS002.1
acf workstream stage done WS002 WS002.1 --evidence "worklog/daily/YYYY-MM-DD.md" --clear-current
acf workstream sync --dry-run --json
acf workstream archive-candidates --json
acf workstream archive-draft --date YYYY-MM-DD --json
acf workstream archive WS002 --reason "reviewed in worklog/archive-drafts/YYYY-MM-DD.md" --json
acf feedback list --status Open --json
acf feedback triage docs/ai F001 --next-action "进入任务计划评估。" --json
acf feedback done docs/ai F001 --result "已整理。" --evidence "active/Task_Plan.md T001" --json
acf feedback archive-candidates --json
acf feedback archive docs/ai F001 --reason "已整理到 active/Task_Plan.md T001" --json
acf plan stage add --id T001.1 --parent T001 --title "任务阶段"
acf plan stage list --json
acf plan stage set --id T001.1 --status Active --next-action "完成阶段"
acf plan stage done --id T001.1 --evidence "worklog/daily/YYYY-MM-DD.md"
acf workstream block WS002 --reason "等待依赖"
acf workstream cancel WS002 --reason "方向取消"
acf workstream list
acf workstream show WS001
acf new task --title "实现一个维护任务" --goal "写清当前目标。"
acf new source --title "资料标题" --type "文档" --location "https://example.com" --relation "说明为什么相关。"
acf new reference --title "设计文档标题" --summary "一句话说明。" --body "核心内容。"
acf new rule --title "规则标题" --condition "何时读取。" --purpose "索引用途。" --rule "具体规则。"
acf new feedback --type "需求" --content "待整理反馈。" --source "2026-05-08 user"
acf new human-note --type "想法" --content "人工异步笔记。"
acf human index sync --json
acf human list --status Open --json
acf human mark reports/example.md --status Extracted --extracted-to reference/Example.md
acf new worklog --summary "完成一次上下文维护。"
acf new worklog --summary "补记一次上下文维护。" --append --json
acf new adr --title "记录一个重要决策" --summary "一句话摘要。" --decision "具体决策。"
acf writeback draft --name "session-note" --text "会话结束回写建议。"
acf edit section get active/Context.md --heading "## 当前有效事实" --json
acf edit section append active/Context.md --heading "## 当前开放问题" --text "1. 新问题。"
acf edit table upsert reference/Sources_Index.md --key-column "资料" --key "资料标题" --cell "状态=Useful"
acf check
acf check --strict
acf log status --json
acf log feedback --type Problem --source manual --related-command "workstream add" --text "实际使用反馈。" --json
acf log tail --limit 20 --json
acf log summarize --json
acf log summarize --days 7 --errors-only --json
acf log prune --days 30
acf version show --json
acf version set v0.0.3.34 --dry-run --json
acf status --json
acf new task --title "预览任务" --goal "只预览。" --dry-run --json

未安装全局命令时，在本仓库开发环境中也可以使用 uv run acf ...。

命令说明：

• status：从当前目录向上自动发现上下文，输出项目根、上下文目录、profile、当前任务状态和检查结果。

• init：从 template/ 生成标准或简化上下文目录。

• init --force-root-agent：在根入口已存在时重写根薄入口。

• simplify：从已有上下文生成只包含核心文件的简化版本，并保留真实 ADR 与 daily worklog，排除占位模板文件。

• upgrade：非破坏式补齐新版本上下文结构，包括标准 profile 的 human 层和 Human_Index.md、反馈归档目录和 active -> reference 规划依据追溯入口；不自动移动或覆盖 Active 当前任务；自定义旧文档无法识别时会追加 canonical marker 包围的升级说明块。

• plan init|add-task|set-task|focus|status、plan reference list|add|remove 和 plan stage list|add|set|done：维护 active/Task_Plan.md 中的大任务、子任务板、## 规划依据 和 ## 任务阶段 表；plan reference add --path reference/X.md --purpose "用途" 只记录 reference 路径和一句话用途，可用 --sync-current-task 显式同步到 Active active/Current_Task.md 的输入材料；Task Stage CLI 只维护任务阶段表，要求 T001.1 这类阶段 ID 归属于已存在父任务，不创建 task object 单文件，不自动修改 active/Current_Task.md，也不自动联动 Workstream。

• plan complete：在子任务完成后将大任务计划标记为 Done。

• linkify：把默认范围内安全识别到的本地路径引用转换为可点击 Markdown 链接；默认处理 active、reference、rules、decisions、Worklog_Index 和 Archive_Index，跳过 archive 详情和 daily worklog；--include-archive / --include-worklog-daily 可显式扩大范围，--allow-missing 可允许缺失目标。

• link add：向上下文内指定 Markdown 文件的小节追加链接 bullet；--target-heading 会生成并校验 Markdown heading anchor，重复链接默认拒绝，--force 才允许重复。

• task start|done|block|clear：从任务板启动、完成、阻塞或清空当前小任务；task start 默认拒绝启动依赖未完成的子任务，除非传入 --force。

• archive current-task|task-plan|list|sync：归档旧当前任务或旧大任务计划，并更新 archive 索引；归档 current task / task plan 时会按归档文件的新位置重写本地 Markdown 相对链接，并追加 ACF:ARCHIVE:RECORD marker；sync 从 archive/tasks、archive/plans 和 archive/workstreams 重算 ACF:ARCHIVE:INDEX-GENERATED marker 内表格，优先使用归档 record marker 恢复 Task/Plan 归档原因，旧索引首次接入 sync 时需显式 --init-marker，旧手写表会保留在 marker 外。

• decisions sync：从 decisions/ADR-*.md 重算 ACF:DECISIONS:INDEX-GENERATED marker 内表格；旧索引首次接入 sync 时需显式 --init-marker，命令只替换 marker 内内容，不修改 ADR 正文。

• knowledge draft|apply|list|show|mark|sync：生成可审阅 Knowledge 草案，审阅后写入可复用经验索引，并可用 sync 从 reference/knowledge/K*.md 重算 ACF:KNOWLEDGE:INDEX-GENERATED marker 内表格；apply 默认拒绝疑似重复条目，可用 --allow-similar 显式覆盖；旧索引首次接入 sync 时需显式 --init-marker。

• feedback list|triage|done|reject|archive-candidates|archive：维护 active/Feedback_Inbox.md 的确定性生命周期；triage/done/reject 只更新状态和处理结果，不自动转写 Context、Task、ADR 或 Knowledge；archive-candidates 只读列出 Done/Rejected 候选，archive 只显式移动单条反馈到 archive/feedback/YYYY-MM dot md。

• human index sync|list|mark：维护 human/Human_Index.md；index sync 机械扫描 Human_Notes.md、human/weekly/*.md 和 human/reports/*.md 并补缺失索引行，不删除旧行、不覆盖人工状态；list 按状态或类型查看 human 材料；mark 按 ID 或路径把条目标记为 Reviewed、Extracted 或 Archived 并可记录整理目标。

• review stale：只读检查默认注意力入口是否可能过期，报告 stale candidates，不判断内容真假、不写文件；支持 --json 和 --days。除了日期型 stale signal，还会机械报告 Done 的非空 active/Current_Task.md / active/Task_Plan.md 仍被保留时的 current_task_terminal_retained / task_plan_terminal_retained。JSON 输出包含 summary.total、summary.by_kind、summary.by_path，每个候选包含 kind、signal、path、reason、age_days、status 和 suggested_action；next_actions 会在 clean 状态或按 stale kind 给出机械下一步建议。

• audit context：只读检查 active 层上下文污染候选，不判断事实真假、不写文件、不生成 patch、不接入 check --strict；MVP 只报告 active_section_too_long、stale_current_task_or_workstream_stage 和 terminal_conclusion_not_merged（ReadyToMerge 待合并或 Done 缺合并结果）。JSON 输出包含 candidates、summary.total、summary.by_kind、summary.by_path、summary.by_severity 和 next_actions。

• doctor：面向人和 AI 的上下文健康诊断入口，默认只读并复用 check 结果，同时报告 Task_Plan / Current_Task 生命周期漂移、终态 Workstream authority scope 残留、Workstreams / Archive generated index 漂移、Workstream 协议漏 Merging、Decisions_Index 摘要截断、Sources_Index 本地文件缺失、active 过厚、根目录探针输出和本地数据副本 hash / missing evidence。attention hygiene 会直接复用 review stale 的机械 current_task_terminal_retained、task_plan_terminal_retained、context_missing_review_marker 和 context_review_stale signals；这些 finding 是 warning / draft-only，不进入 check --strict，也不会自动裁决或改写自然语言事实。支持 --json、只读 --projects、单项目 --fix safe|evidence、--report、--draft-semantic、--force、--dry-run 和 --check-after。--fix safe 只做确定性低风险修复，例如清空无下一任务的 Done 焦点、修正 Current_Task 中明确回写目标行且无额外任务引用的目标 ID、移除终态 Workstream authority assigned: scope、同步 Workstreams / Archive generated index 和补齐 Workstream 协议 Merging；语义项只进入 report 或 writeback draft，数据 hash 证据只读取项目根内的相对路径。

• curate draft：复用 review stale 的 stale candidates 生成 worklog/curation-drafts/YYYY-MM-DD.md 注意力治理草案；空信号时不创建草案，同名草案已存在时安全拒绝；支持 --json、--dry-run、--days 和 --name。

• workstream init|status|list|dashboard|archive-candidates|archive-draft|archive|sync|show|context|add|reserve|set|block|cancel|merge-request|merge-start|ready|done|claim|scope-add|guard|note|focus 和 workstream stage add|list|done：显式启用可选 Workstream 层，读取并行目标线索引与详情 metadata，并维护强隔离状态转换、合并请求、完成证据、scope claim/扩权、详情备注、内部阶段焦点和显式归档；reserve 是可选的 Git-aware 编号预约入口，只在 primary branch 创建并提交 detail/index，不创建 branch/worktree；原 add 行为保持不变；context WS001 输出 AI 专属任务入口，guard 检查变更文件是否符合当前 Workstream 写入边界，完成或切换状态前优先用 --files 显式传入本次修改文件做强验收；scope-add 以工具化方式扩展 read/write scope 并写入 Activity Log，dashboard 显示冲突、陈旧任务、缺 evidence 和待合并 authority 目标；Workstream 类型为 Task / Merge / Maintenance，Task 不能直接写 authority 文件，Active 类 Workstream 默认禁止重叠 owned: 写入，shared: 必须指定 merge_owner 或 serial coordination；archive-candidates 只读报告 Done / Cancelled Workstream 的归档候选和 blocked_by；archive-draft 写入 worklog/archive-drafts/ 供人工或 AI 审阅；archive WS001 --reason "..." 只在显式指定单个终态 Workstream 时移动详情、清理 active 索引并写入 archive/Archive_Index.md；sync 只根据 active/workstreams/*.md front matter 更新 active/Workstreams.md，不会删除缺详情的旧索引行；Workstream 详情可用 optional current_stage 和 ## 阶段 表记录内部阶段焦点，stage add/list 只维护详情文件，focus 不更新全局 Current_Task，stage done 要求 evidence 且完成当前阶段时需要 --clear-current；merge_targets 记录候选合并目标，ReadyToMerge 表示任务产物完成，ready 需要人工确认参数 --human-approved，Merging 表示 Merge/Maintenance 正在合并，Done 需要 --merge-resolution 写入合并或处置结果；add --goal 可在创建时写入详情目标，set --goal 可替换已有详情目标，--write-scope 必须使用 TYPE: PATH 格式，例如 owned: src/foo.py；upgrade 和旧项目默认不启用 Workstream。

• worktree create|attach|verify|list|audit|sync|merge-plan|merge|artifact-plan|artifact-migrate|close|resume：供 AI 按任务需要调用的可选 Git 生命周期能力。创建 Workstream 不会隐式创建 worktree；create 同时支持正式 WS 与 bugfix/docs/experiment/investigation/maintenance/refactor/release 非 WS 任务。每次 merge 都在临时 integration worktree 中产生和验证候选，primary checkout 只执行路径碰撞保护后的 fast-forward promotion，因此可以保留无关 staged/unstaged/untracked 修改；短时锁、index、路径碰撞和 HEAD 推进会有限等待或自动重规划，稳定冲突留在 integration worktree 并可用 operation ID 恢复。ignored/untracked 结果必须通过 artifact handoff 分类和摘要验证后才能 promotion/close。所有写操作默认只输出计划，显式 --apply 后才执行；实现继续禁止自动 stash、reset、clean、rebase、push、branch -D 和静默解决冲突。唯一内部例外是 close 已证明 semantic-clean 且只剩 stat_only_paths 时，可用 git worktree remove --force 作为 raw-Git 兼容桥；它不授权移除真实 dirty worktree。完整说明见 docs/Worktree_Lifecycle.md。

Worktree lifecycle 的 clean 使用只读 semantic Git clean：staged、untracked、真实 unstaged diff、rename/delete/type/mode/unmerged/submodule 仍是 dirty；仅普通 tracked unstaged M 且 read-only Git diff 证明 index 与规范化 working-tree 内容完全相同时，归入 stat_only_paths 而不阻塞 verify/sync/merge/close。诊断统一使用 GIT_OPTIONAL_LOCKS=0，不会用 update-index --refresh 修改 index。新 reservation 的 ## Workspace 只持久化稳定 slug 与“local registry/verify/list 为机器绑定权威”的说明，不保存 mode:none 或绝对路径；Open reservation/create 的 next_actions 会明确提示先执行 acf workstream set WSxxx --status Active。

• continuation init|configure|list|migrate|doctor|coordination status|coordination attempt|coordination challenge|claim|assert-owner|heartbeat|progress|effect prepare|effect update|effect list|workspace status|workspace intent|workspace adopt|workspace refresh|reconcile|recover|renew|checkpoint|release|pause|resume|prompt|issue：为外部 AI scheduler 或人工长任务提供有界续跑控制。init --profile standard|long-running 可选择时序配置；已有 task 使用 continuation configure --profile long-running 原位更新，无需 init --force。long-running profile 为 scheduler 60 分钟、lease TTL 180 分钟、renew 45 分钟、heartbeat 建议 10 分钟、stale threshold 25 分钟；这些 timing 只服务 lease liveness，不是 execution-duration target、工作配额或汇报周期。新 runner 用 coordination attempt 记录 compact current-goal intent：无 owner 时只成为 claim candidate；遇到 fresh owner 时返回 live_owner_observed、不自动 challenge，并允许 duplicate scheduler wake 在不改变 task 状态的前提下让行；只有 stale / legacy-unverified owner 才自动 open/join generation-bound challenge。显式 coordination challenge 仍可用于独立证据表明需要重新确认 ownership 的场景，但 challenge 本身不授予写权限。只有通过 lease_id + generation + fence_token 的 owner-protected continuation 操作才是 authenticated owner response；challenge timeout 也只产生 ownership_forfeiture_candidate，仍必须 formal reconcile workspace/HEAD/effect/identity 后才能 generation+1 recover。prompt --runner-id <runner> 将 caller identity 与 lease owner 对照，并通过 owner_context 稳定暴露 current owner / verified live other owner / stale-or-unverified / expired / no-owner；旧调用未传 runner-id 时保持保守的 caller-unknown 分类，不武断宣称 duplicate。workspace manifest v3、legacy adoption、task-owned handoff、effect replay protection 与 generation fencing 继续保持既有安全语义。generated prompt 改为 state-conditioned progressive disclosure：always-on 只展示目标、默认计划、authority refresh、continuous/hard-stop contract、owner 摘要和当前 relevant action，claim、duplicate、recovery、workspace provenance、effect reconciliation 细节只在对应状态出现时展开。final response、commit/checkpoint/Gate、timing 的既有非停止语义继续保留。详细设计见 Continuation Control。
• continuation compact state 中历史型摘要 completed / evidence_refs / verification 使用最多 64 项的 rolling window；超过容量时保留最近项，不会再把 state.json 写到自己无法读取的状态。constraints / open_questions / plan_refs 继续严格限 64 项，超限仍 fail-closed，避免容量管理静默丢失仍有效的安全/计划语义。旧版本遗留的 current-schema history-list overflow 会在读取时惰性压缩，因此升级后 prompt/doctor/reconcile 可先恢复工作，再由下一次合法 state write 持久化 compact 结果；round/effect/coordination 等独立历史账本不受影响。

effect history 采用 replay-safe rollover：current effects.json 到达记录/字节边界时，只把完整 terminal completed|failed records 移入 bounded effects.archive.NNNNNN.json segments；所有 archive 继续参与 logical_key/kind/external_id 去重检查，所以旧 effect 不会因为容量滚动而被重放。任何 prepared|active|unknown record 都留在 current journal；如果 unresolved records 自身已经耗尽容量，ACF 继续 fail-closed，而不是删除或覆盖它们。

continuation prompt --json 同时返回稳定的 identity、current、owner_context、execution_policy、project_context、scheduler_wrapper_contract 和当前 next_actions。execution_policy 在既有 goal-directed continuous / hard-stop contract 上新增 next_action_is_default_execution_plan=true、next_action_requires_authority_refresh=true、active_lease_requires_liveness_verification=true、verified_duplicate_owner_may_end_duplicate_wake=true、duplicate_wake_exit_is_task_stop=false、stale_owner_requires_recovery=true 与 contender_must_create_busywork=false，并继续保留 next_action_is_work_quota=false、final_response_is_terminal=true 等既有字段。scheduler_wrapper_contract.bootstrap_policy=sufficient_high_salience：wrapper 应完整携带 exact existing workspace / project access tool mode / stable ACF upgrade-adaptation / authority refresh / execute-generated-plan / owner disclosure / project constraints / final-response contract，但不得复制 generic contention/recovery/workspace/effect 状态机。

continuation workspace reclassify 是 active fenced owner 的窄恢复工具，不是事后泛化的 workspace intent：durable writer 已结束后，如果某个启动前漏报的真实产出当前被分类为 unexpected_nonoverlap，只有在来源已审阅且提供 durable --evidence-ref 与 --reason 时，才能显式用 --task-owned <path> 纳入任务，或用 --baseline-external <path> 继续保护为外部修改。task-owned reclassification 仍受 bound Workstream direct write scope 约束；已有 conflict、非 unexpected 路径、重叠分类、scope 越界、证据缺失或来源不确定都继续 fail-closed。

ownerless effect recovery 有三条明确、互斥且 fail-closed 的收口路径：已经取得 durable external id 的 effect 必须继续用 --effect-external-id 与外部终态证据做 identity-matched reconciliation；同一 stale generation 若有多个此类 externally-proven terminal effects，可按相同顺序重复 --effect-key、--effect-terminal-status、--effect-external-id，由一个 receipt 原子收口全部 assertions，并共享本次 --effect-evidence-ref 集合。若 write-ahead effect prepare 后能够由外部 authority 明确证明 submit 从未启动，则可在 owner-ended/forfeiture 条件下使用 reconcile --effect-not-started --effect-terminal-status failed --effect-evidence-ref <ref>；该 no-start 分支仍只接受单个 prepared、external_id=null 记录，不能声明 completed，也不能用于 active/unknown effect。若旧版本已经实际执行了本地确定性动作，但当时只留下 prepared + external_id=null，且 durable local artifact/state/hash 等 authority evidence 已明确证明 terminal 结果，则可显式使用 --effect-local-terminal（可一次对多个 effect 使用同一 receipt）；它只接受仍为 prepared 且没有 external id 的记录，不能和 --effect-not-started 或 --effect-external-id 混用，active/unknown effect 继续拒绝。

acf continuation list [<worktree>] --json 只读展示当前 ACF_HOME 中的 continuation identity、task_id/workstream_id、timing profile、每个 state 文件的 schema 与 current / migration_available / blocked 兼容状态；--all-projects 可扫描全部 path-hash namespace。已知 legacy workspace schema 使用 acf continuation migrate ... --dry-run --json 先生成迁移计划，并在没有 lease record 时显式 --apply --reason ...；迁移只改已声明可兼容的 state 文件并写 last_migration.json receipt，round/effect/coordination/reconcile/recovery 等历史文件用 byte digest 证明未被改写。未知或未来 schema 不自动猜测，继续 fail-closed；外部 scheduler 不得手工编辑 ~/.acf JSON。

Workstream 编号预约与可选 Worktree

acf workstream reserve --title "任务" --slug task-slug --owner codex --apply --json
acf worktree create --workstream WS005 --apply --json
acf worktree verify --workstream WS005 --json

第一条命令只预约并提交 WS 编号；第二条只有在 AI 判断需要隔离环境时才调用。未配置或未调用 acf worktree 的项目继续使用原有 Workstream 和上下文逻辑。

reserve --apply 不要求 primary checkout 完全 clean：与 reservation detail/index 无关的 staged、unstaged、untracked 修改会被保留；reservation 路径自身或父子路径发生冲突时才会 fail-closed。

Workstream guard 模式

acf workstream guard 检查的是“变更文件是否符合当前 Workstream 的写入范围”，不是默认独占整个工作区。多个 agent 或多个 Workstream 在同一仓库并行时，完成、ready、done 或切换状态前，优先显式传入本次要验收的文件集：

acf workstream guard WS001 --files src/foo.py docs/ai/active/workstreams/WS001.md --json

场景	推荐命令	语义
本次变更文件明确	acf workstream guard WS001 --files path1 path2 --json	权威文件集强验收；失败表示这些文件越过当前 Workstream scope。
单个文件验收	acf workstream guard WS001 --file path --json	--files 的单文件形式，可重复传入。
快速查看当前 git diff	acf workstream guard WS001 --from-git --json 或裸 guard	读取 git diff；若存在其他 Workstream 或未归属 dirty files，结果不能直接作为完成证据。
旧式整工作区排他检查	acf workstream guard WS001 --workspace --strict-workspace --json	要求整个工作区没有无关改动；只适合单线或需要强制清空工作区的场景。
禁止 shared 写入	acf workstream guard WS001 --files path --owned-only --json	shared scope 也会失败，用于严格 ownership 验收。

只有显式文件集模式可作为完成或切换状态的强验收证据；裸 guard 和 --from-git 适合发现当前工作区风险，不应在存在并行 dirty files 时替代 --files。

• new task：生成或重置 active/Current_Task.md，默认拒绝覆盖 Active 任务，除非传入 --force。
• new source：向 reference/Sources_Index.md 添加或更新资料索引行，默认拒绝重复资料标题，除非传入 --force。
• new reference：在 reference/ 下创建长期按需读取的 Markdown 文档；默认使用标题 slug 生成文件名，也可用 --file reference/X.md 指定路径；拒绝写到 context 外或 reference/knowledge/ 托管目录。
• new rule：在 rules/ 下创建按需规则文件，并更新 rules/Rules_Index.md 的按需规则表；minimal context 首次使用时会补一个轻量 Rules_Index，不把 whole context 升级为 standard。
• new feedback：向 active/Feedback_Inbox.md 添加反馈行，自动分配下一个 Fxxx，默认状态为 Open，默认来源包含当天日期；重复 ID 需传入 --force 才能覆盖。
• new human-note：向标准 profile 的 human/Human_Notes.md Inbox 添加人工异步笔记行，自动分配下一个 Hxxx，并同步更新 human/Human_Index.md；minimal context 没有 human 层时会拒绝，建议使用 new feedback 或先升级为 standard。
• new worklog：按日期生成 daily worklog，并更新 worklog/Worklog_Index.md；同日已有记录且需要补记时使用 --append，需要重建时使用 --force，二者不能混用。
• new adr：生成下一个 ADR 文件，并更新 reference/Decisions_Index.md。
• writeback draft：把不能安全直接落盘的会话结束回写建议保存为注意力治理草案；可确定的任务、计划、worklog、Knowledge 或归档变化应优先写入对应文件或草案。
• edit section get|replace|append：读取、替换或追加指定 Markdown 标题下的 section body。
• edit table upsert：按 key column 更新或追加 Markdown 表格行。
• check：检查目录结构、必需文件、乱码、空文件、内部引用、human index 路径、状态枚举、索引一致性、任务板、任务阶段注册、archive、Knowledge 和显式启用的 Workstream；Workstream 检查包含 optional current_stage 与 ## 阶段 表一致性、strict 下 Done 阶段 evidence、Workstreams 索引与详情 front matter 一致性、Task authority 写入门禁、Active 类 Workstream 写入冲突、shared: merge owner/serial coordination 要求和 merge_targets 合并请求要求；没有 active/Workstreams.md 时不触发 Workstream 检查。
• log enable|disable|status|tail|summarize|projects|feedback|prune：管理本地使用状态日志，默认开启以便开发调试收集反馈，可用 log disable 按项目关闭；log projects --scan-root <path> --json 可只读盘点全局日志中的项目并匹配磁盘上的 context root；普通 usage event 不记录正文，显式 log feedback --text/--input 才记录人工反馈正文。
• version show|set：查看或一键更新 CLI、包配置和本地元数据版本号。

check、new ... 和 writeback draft 可以省略上下文路径；省略时 CLI 会从当前目录向上查找 docs/ai、docs-acf/ai 或上下文根目录。显式传入路径时，以显式路径为准。

status、check、review stale、audit context、doctor、feedback list|archive-candidates、workstream status|list|archive-candidates|show 和 edit section get 支持 --json 输出。archive-draft、archive、doctor --fix safe|evidence、doctor --report、doctor --draft-semantic、feedback triage|done|reject|archive、curate draft 和其他写命令支持 --json、--dry-run、--check-after，并会输出 changed files；--dry-run 只验证和预览，不落盘。

edit 命令只操作上下文根目录内已有的 .md 文件，拒绝路径穿越和非 Markdown 目标。它提供的是 section/table 级确定性编辑原语，不做语义判断，也不是通用 Markdown 编辑器。

PowerShell 中反引号是转义字符。写入包含 Markdown 反引号或多行正文时，优先使用 --input <file>，避免命令行字符串被 shell 改写。

log 命令默认开启并写入用户级全局目录 %USERPROFILE%\.acf\projects\<project-id>\（Windows）或 ~/.acf/projects/<project-id>/（macOS/Linux），也可通过 ACF_HOME 指定根目录。自动 usage event 不写入项目 worklog/，也不记录 --text 正文、stdin 内容、Markdown diff 或完整 stdout/stderr；事件只保存命令元数据、结果、相对路径、changed files，并保存本机可解释的 project_root / context_root 绝对路径用于用户自己的审计。需要保存实际使用反馈时，显式运行 acf log feedback --text ... 或 --input <file>，该命令会把反馈正文作为 event_kind=feedback 事件写入同一日志。acf log projects --json 只读汇总全局日志，--scan-root 可把旧日志 project id 映射到真实 context root，--log-root 可读取测试或备份日志目录。日志写入带用户级锁，配置和 prune 重写使用原子替换；自动日志写入失败不会改变原命令退出码。

JSON 输出包含稳定字段：schema_version、ok、error_code、next_actions。检查失败时 error_code 为 check_failed，next_actions 给出 AI 可直接读取的后续动作。

AI 调用 new worklog 的推荐模式：

目标状态	推荐命令	结果
不确定是否已有今日 worklog	acf new worklog --summary "..." --dry-run --json	根据 error_code 判断下一步
今日 worklog 不存在	acf new worklog --summary "..." --json	创建
今日 worklog 已存在，想补记	acf new worklog --summary "..." --append --json	追加到稳定 anchor
今日 worklog 已存在，想重建	acf new worklog --summary "..." --force --json	替换
anchor 缺失	不自动修复	返回 ANCHOR_NOT_FOUND

new worklog --append 的 JSON 面向 AI 稳定解析：target 和 changed_files 使用 repo-relative POSIX slash 路径；成功输出包含结构化 warnings 数组；insert_after_line 是 1-based 行号；--dry-run --json 不写文件；append 不是幂等操作，每运行一次都会新增一段内容。目标已存在但未传 --append 或 --force 时，error_code=TARGET_EXISTS_APPEND_REQUIRED；--append --force 返回 APPEND_FORCE_CONFLICT；anchor 缺失返回 ANCHOR_NOT_FOUND。

退出码和错误分类：

• 0：成功。
• 1：检查失败，error_code=check_failed。
• 2：输入错误，error_code=input_error。
• 3：安全拒绝，例如重复写入或需要 --force，error_code=safety_refused。
• 70：非预期运行时错误，error_code=runtime_error。

check 默认关注结构完整度；--strict 适合检查已投入使用的项目上下文，会把占位符残留视为错误。

旧版本上下文升级

旧项目升级到当前模板结构时，先预览再应用：

acf status --json
acf upgrade --plan --json
acf upgrade --dry-run --json
acf upgrade --check-after --json
acf check --strict --json

upgrade --plan --json 是只读升级评估：不写项目文件、不写 usage log、不获取写锁，输出 readiness、risk_summary、findings、structural_changes、manual_actions 和 recommended_commands。它把“可由 upgrade 补齐的结构问题”和“占位符、断链、Workstream lifecycle 等语义债务”分开，帮助 agent 判断是否可以先做结构升级。

upgrade 只补齐当前 schema 缺失的 active/Task_Plan.md、标准 profile 的 human 层（含 human/Human_Index.md）、archive、archive/feedback 和 Knowledge 文件/目录，并为旧 active/Task_Plan.md 补 ## 规划依据 结构、为 Active active/Current_Task.md 的 ## 输入材料 保守追加规划依据提示；它不移动旧内容、不自动归档任务、不覆盖 Active active/Current_Task.md，也不自动判断哪些 reference 是正确依据。--json 输出包含 detected_features、planned_changes、skipped_changes 和 changed_files，用于审查升级原因、预期写入和已跳过项。如果旧任务或旧计划需要归档，升级后再显式运行 acf archive current-task 或 acf archive task-plan。对高度自定义的旧入口文档，upgrade 会追加 ACF:UPGRADE:NOTES marker 块而不是强行重排原文；旧 ACF:UPGRADE-NOTES marker 保持兼容并在可管理文档中迁移。

模板占位符统一使用 【ACF:KEY|提示】。Markdown 表格单元格里使用无提示形式 【ACF:KEY】，避免 | 破坏表格。机器维护块统一使用 <!-- ACF:<DOMAIN>:<PURPOSE>:START --> ... END -->，例如 ACF:UPGRADE:NOTES、ACF:ARCHIVE:RECORD 和 ACF:WORKSTREAM:ARCHIVE-RECORD；旧 marker 仍兼容，check 会给出 future warning。

如果全局 acf 未安装，可在本仓库源码环境中对其他项目运行：

uv run --project path/to/ai-context-framework acf upgrade --plan --json
uv run --project path/to/ai-context-framework acf upgrade --dry-run --json

维护与验证

修改模板或 CLI 后运行：

uv run acf check template
uv run acf check --strict
uv run python -m unittest

发布前可额外运行本地最小 smoke runner：

uv run python scripts/minimal_smoke.py --acf uv run acf

该脚本只使用隔离临时目录和 CLI JSON 输出，覆盖 init -> nested status/check、new worklog create/append/error_code 和 Workstream 最小 happy path。它不做真实项目批量评测、漂移样本诊断或复杂 upgrade 审查。

发布前完整验收（包含 wheel/sdist 构建、隔离安装和 console script smoke）：

uv run python scripts/release_check.py --mode full

只验证发布制品安装链路：

uv run python scripts/release_check.py --mode package

修改 template/、默认上下文结构、打包清单或 acf upgrade 行为时，还必须评估旧版本上下文升级兼容性：新增结构同步到 init 文件清单、upgrade 补齐清单和 data-files，并用 init/upgrade 测试覆盖旧项目可非破坏式升级。快速升级兼容矩阵随单元测试运行；发布前可运行完整矩阵：

uv run python scripts/upgrade_matrix.py --mode full --acf uv run acf

自动化边界和后续路线见 docs/Automation.md。