ai-context-framework 0.0.3.58__tar.gz

ai_context_framework-0.0.3.58/CHANGELOG.md

@@ -0,0 +1,106 @@
+# 更新日志
+
+本文件记录 ACF 稳定版本的用户可见变化。完整实现证据、测试矩阵和 Workstream 归档仍保存在 `docs/ai/archive/workstreams/` 与 `docs/ai/worklog/`；本文件只保留发布级摘要。
+
+## v0.0.3.58 — 2026-08-10
+
+### 发布与安装
+
+- 新增 `scripts/release_check.py`，覆盖发布前检查、wheel/sdist 构建、隔离安装和 console script smoke。
+- 新增 uv 一键安装/更新脚本，以及 GitHub Actions CI 和 `v*` tag PyPI 发布 workflow。
+
+## v0.0.3.57 — 2026-08-10
+
+### 修复
+
+- `acf workstream reserve --apply` 不再因为 primary checkout 存在其他 agent 的无关 staged、unstaged 或 untracked 修改而失败。
+- 预约提交改为只提交 reservation detail/index；只有预约路径本身或父子路径发生冲突时才 fail-closed，并保留其他本地修改。
+- 补充预约路径冲突、并行 dirty 状态保留和冲突修复后恢复测试及对应 JSON error contract。
+
+### 验证
+
+- 通过 template/strict check、编译检查、diff check 和分片 unittest；分片覆盖 423 项测试。
+- 完整 `uv run python -m unittest` 在工具 10 分钟窗口内超时，但各测试分片均通过，未将聚合超时计作通过。
+
+## v0.0.3.56 — 2026-08-06
+
+### 新增
+
+- `acf worktree merge` 统一改为临时 integration worktree 执行：真实 no-ff merge、冲突解决和 post-check 不再发生在 primary checkout；primary 只执行候选验证后的 fast-forward promotion。
+- primary checkout 允许保留与候选无碰撞的 staged、unstaged 和 untracked 修改；merge-plan 输出结构化工作区快照、候选写入集合、相同重叠和分歧碰撞。
+- 新增有限等待、指数退避、lock heartbeat、stale-lock 安全隔离、primary/source HEAD 自动重规划和 operation v2 resume。
+- 新增 `acf worktree artifact-plan|artifact-migrate`，对 ignored/untracked 结果执行显式分类、复制或稳定引用和 SHA-256 验证；普通路径默认 `unknown`，不能静默删除。
+- 冲突、post-check 失败和 artifact 未完成时保留 integration worktree；修复或分类后使用原 operation ID 继续。
+- close 与 merge 共用来源 lifecycle 锁，支持 Windows 文件占用退避、部分成功 journal 和幂等恢复。
+
+### 配置与安全
+
+- 新增 `primary_dirty_policy = "allow_non_overlapping"|"require_clean"`；两种策略都使用同一 integration 引擎，不恢复旧的 primary direct merge。
+- 新增 `artifact_cache_patterns` 和 `artifact_discardable_patterns`；只有项目配置或本次 CLI 明确声明的路径才自动放行。
+- 相同 untracked/ignored 重叠只在内容、mode 和类型全部与候选一致时使用可恢复 quarantine；promotion 失败会原子恢复，成功后才删除冗余副本。
+- 继续禁止自动 stash、reset、clean、rebase、force、push 和静默冲突选择。
+
+### 验证
+
+- 新增临时真实 Git 仓库场景，覆盖无关 staged/unstaged 保留、相同/不同重叠、ignored 碰撞、短时路径竞争、锁等待、HEAD 推进重规划、冲突解决、post-check 修复、artifact 迁移、close 重试和部分恢复。
+- 完整测试、模板/strict check、构建制品、隔离安装和真实 dogfooding 升级记录见 2026-08-06 worklog。
+
+## v0.0.3.55 — 2026-08-04
+
+### 变更
+
+- `acf status|next` 未显式选择 Workstream 时改为 `GlobalOnly`：只披露全局上下文文件指针和 Workstream 摘要，不再因为一个或多个 active-class Workstream 自动进入任务。
+- `attention: Now/Next/Waiting/Retained` 降级为 dashboard 管理元数据，不再决定默认上下文入口。
+- 新增 `acf status|next --workstream WSNNN` 显式选择；Active `Current_Task` 唯一绑定和经过 registry/path/branch/common-dir 校验的专属 worktree 也可作为明确选择来源。
+- 选择结果采用两级渐进式披露：状态命令只返回 pointer-only 入口，必须再调用 `acf workstream context WSNNN` 才读取专属 detail/read_scope，并继续按需读取 reference/output。
+- 显式来源冲突或选择不存在、非活动 Workstream 时返回 `SelectionConflict` / `SelectionInvalid`，保持全局上下文并 fail-closed。
+
+### 兼容性与安全
+
+- 原 Workstream/Worktree 生命周期接口和 attention front matter 保持兼容；不要求旧项目批量修改 attention。
+- 多个活动 Workstream 是正常项目状态，不再作为 `Ambiguous`；只有真正的显式选择冲突才报错。
+- 默认 JSON 不包含任一 Workstream 正文、read_scope、reference、output 或专属 worklog 内容，降低 AI 上下文污染风险。
+
+### 验证
+
+- 新增 global-only、pointer-only、Current Task、显式选择、verified worktree、冲突/无效选择和专属预算隔离测试。
+- 完整测试、Python 3.10、升级矩阵、模板/strict check、wheel 隔离安装和生产 console-script smoke 见 WS006 发布证据。
+
+## v0.0.3.54 — 2026-08-04
+
+### 新增
+
+- 新增 `acf workstream reserve`：在 primary branch 上预约并提交唯一 Workstream 编号，扫描 active/archive/index、Git refs、worktree registry 和 operation journal；创建 Workstream 时不隐式创建 branch/worktree。
+- 新增 `acf worktree create|attach|verify|list|audit|sync|merge-plan|merge|close|resume`，覆盖正式 Workstream 与分类非 Workstream 的完整 Git worktree 生命周期。
+- 新增 `.acf/project.toml` 可选 Git 配置、Git common-dir operation journal、registry 和分层操作锁。
+- 新增冲突预演、冻结 source/base commit、`--no-ff` 合并、部分失败恢复和幂等关闭。
+- 新增 `docs/Worktree_Lifecycle.md` 教程、真实 Git 仓库测试矩阵和安装态完整生命周期 smoke。
+
+### 兼容性
+
+- 原 `acf workstream add`、状态流转、guard、archive 及不创建 worktree 的项目逻辑保持不变。
+- 未配置或未调用 `acf worktree` 时，旧项目不依赖 Git worktree 配置。
+- 支持 Python 3.10 及以上；Python 3.10 核心矩阵 46/46 通过。
+
+### 安全边界
+
+- 所有 Git 写命令默认只输出计划，显式 `--apply` 才执行。
+- 不自动执行 `stash`、`reset`、`clean`、`rebase`、`branch -D`、`worktree remove --force`、`push` 或冲突解决。
+- 错误仓库、detached HEAD、dirty 状态、路径占用、分支占用、primary 前进和内容冲突均 fail-closed。
+
+### 验证
+
+- 完整测试：353/353。
+- 新增 worktree 生命周期测试：34/34。
+- 完整旧项目 upgrade matrix、模板检查、dogfooding strict check、源码安装态 smoke、wheel 隔离安装 smoke 和生产 `acf.exe` 生命周期 smoke 全部通过。
+- 发布 merge commit：`c16e0d1925ae444bec74ecdd4eeea72b74f873e5`。
+
+## v0.0.3.53 — 2026-08-04
+
+- 完善 Workstream guard 文件集强验收、旧项目升级迁移说明和注意力路由。
+- 明确裸 `guard` / `--from-git` 仅用于快速查看；完成与状态切换优先使用 `--files`。
+
+## v0.0.3.52 — 2026-06-09
+
+- 发布旧项目升级审计、Workstream-first 上下文入口和模块化 CLI 稳定基线。
+- 提供 `upgrade --plan --json`、全局项目日志盘点及稳定安装入口。

ai_context_framework-0.0.3.58/MANIFEST.in

@@ -0,0 +1,9 @@
+include CHANGELOG.md
+recursive-include template *
+include docs/Worktree_Lifecycle.md
+include scripts/worktree_release_smoke.py
+include scripts/release_check.py
+include scripts/install_acf.ps1
+include scripts/update_acf.ps1
+include scripts/install_acf.sh
+include scripts/update_acf.sh

ai_context_framework-0.0.3.58/PKG-INFO

@@ -0,0 +1,499 @@
+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] <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
+
+正式发布版本安装（推荐）：
+
+```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 <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` 适合检查已投入使用的项目上下文，会把占位符残留视为错误。
+
+### 旧版本上下文升级
+
+旧项目升级到当前模板结构时，先预览再应用：
+
+```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】`，避免 `|` 破坏表格。机器维护块统一使用 `<!-- ACF:<DOMAIN>:<PURPOSE>:START --> ... 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`。