ai-context-framework

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

当前推荐版本

v0.0.3.59 是当前推荐版本。在 v0.0.3.58 发布/安装闭环基础上新增模型无关的 acf continuation：外部 Scheduled Task、其他 scheduler 或人工多轮任务可直接对既有 clean worktree 使用用户级 bounded state、单写者 lease、pause/resume 和 fail-closed recovery，不需要为了续跑控制重建 worktree，也不会把运行态写入项目 Git。

• 版本变化：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。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；支持 --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、force、push 和静默解决冲突。完整说明见 docs/Worktree_Lifecycle.md。

• continuation init|doctor|claim|renew|checkpoint|release|pause|resume|prompt：为外部 AI scheduler 或人工长任务提供有界续跑控制。状态保存在用户级 ~/.acf，不会因为 lease/checkpoint 更新把目标 worktree 变 dirty；可选绑定 --workstream WSNNN 时复用 ACF 的 registry/path/branch/common-dir 验证。该命令不创建 Scheduled Task、不读取聊天历史、不充当常驻 agent runtime；现有 clean worktree 可以直接初始化，无需重建。详细设计见 Continuation Control。

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。