Metadata-Version: 2.4 Name: ai-context-framework Version: 0.0.3.58 Summary: Model-independent AI context framework templates and CLI. Requires-Python: >=3.10 Description-Content-Type: text/markdown # ai-context-framework 一个模型无关的 AI 上下文管理框架模板。 ## 当前推荐版本 `v0.0.3.57` 是当前推荐的真实项目正式使用稳定版本。该版本保留 `v0.0.3.56` 的 GlobalOnly / pointer-only 上下文路由和临时 integration worktree 合并链，并修复 Workstream 预约的 dirty-primary 门禁：无关 staged/unstaged/untracked 修改可以保留，预约提交只包含 reservation detail/index；只有预约路径本身或父子路径冲突才会阻塞。原 Workstream、reserve、create、sync 及未使用 worktree 的项目行为保持兼容。 - 版本变化：[CHANGELOG.md](CHANGELOG.md) - Workstream/Worktree 教程：[docs/Worktree_Lifecycle.md](docs/Worktree_Lifecycle.md) - 详细 CLI 参数：`acf --help`、`acf workstream reserve --help`、`acf worktree --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] --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 正式发布版本安装（推荐）： ```powershell uv tool install ai-context-framework uv tool update-shell ``` 正式发布版本更新： ```powershell uv tool upgrade ai-context-framework uv tool update-shell ``` 如果已经取得本仓库源码，也可以使用一键脚本： ```powershell pwsh -NoLogo -NoProfile -File scripts/install_acf.ps1 pwsh -NoLogo -NoProfile -File scripts/update_acf.ps1 ``` 开发安装（仅仓库维护或调试安装链路时使用）： ```powershell uv tool install -e . uv tool update-shell ``` 重新打开 PowerShell 后验证： ```powershell Get-Command acf acf --help acf --version acf status --json ``` Windows CMD 可用 `where.exe acf` 查看命令位置。 #### WSL / Linux / macOS 正式发布版本安装（推荐）： ```bash uv tool install ai-context-framework uv tool update-shell ``` 正式发布版本更新： ```bash uv tool upgrade ai-context-framework uv tool update-shell ``` 如果已经取得本仓库源码，也可以使用一键脚本： ```bash sh scripts/install_acf.sh sh scripts/update_acf.sh ``` 开发安装（仅仓库维护或调试安装链路时使用）： ```bash uv tool install -e . uv tool update-shell ``` 重新打开 shell，或按 `uv tool update-shell` 的提示刷新 PATH 后验证： ```bash 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` 或上下文根目录的项目中。 ### 常用命令 ```bash 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](docs/Worktree_Lifecycle.md)。 ### Workstream 编号预约与可选 Worktree ```powershell 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 或切换状态前，优先显式传入本次要验收的文件集： ```bash 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 --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 `，避免命令行字符串被 shell 改写。 `log` 命令默认开启并写入用户级全局目录 `%USERPROFILE%\.acf\projects\\`（Windows）或 `~/.acf/projects//`（macOS/Linux），也可通过 `ACF_HOME` 指定根目录。自动 usage event 不写入项目 `worklog/`，也不记录 `--text` 正文、stdin 内容、Markdown diff 或完整 stdout/stderr；事件只保存命令元数据、结果、相对路径、changed files，并保存本机可解释的 `project_root` / `context_root` 绝对路径用于用户自己的审计。需要保存实际使用反馈时，显式运行 `acf log feedback --text ...` 或 `--input `，该命令会把反馈正文作为 `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` 适合检查已投入使用的项目上下文，会把占位符残留视为错误。 ### 旧版本上下文升级 旧项目升级到当前模板结构时，先预览再应用： ```bash 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】`，避免 `|` 破坏表格。机器维护块统一使用 ` ... END -->`，例如 `ACF:UPGRADE:NOTES`、`ACF:ARCHIVE:RECORD` 和 `ACF:WORKSTREAM:ARCHIVE-RECORD`；旧 marker 仍兼容，`check` 会给出 future warning。 如果全局 `acf` 未安装，可在本仓库源码环境中对其他项目运行： ```bash 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 后运行： ```bash uv run acf check template uv run acf check --strict uv run python -m unittest ``` 发布前可额外运行本地最小 smoke runner： ```bash 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）： ```bash uv run python scripts/release_check.py --mode full ``` 只验证发布制品安装链路： ```bash uv run python scripts/release_check.py --mode package ``` 修改 `template/`、默认上下文结构、打包清单或 `acf upgrade` 行为时，还必须评估旧版本上下文升级兼容性：新增结构同步到 init 文件清单、upgrade 补齐清单和 data-files，并用 init/upgrade 测试覆盖旧项目可非破坏式升级。快速升级兼容矩阵随单元测试运行；发布前可运行完整矩阵： ```bash uv run python scripts/upgrade_matrix.py --mode full --acf uv run acf ``` 自动化边界和后续路线见 `docs/Automation.md`。