fluffy-context 0.7.7 → 1.0.0-beta.1

package/README.md

@@ -1,645 +1,202 @@
 # fluffy-context
 
-本地优先、Agent 无关的 Context 与 Knowledge Runtime，帮助 AI 编程 Agent 保存任务状态、恢复工作上下文、复用已验证共识，并生成有界且可追溯的上下文输入。
+**让项目记住 AI 已经做过的工作，让下一次对话接着往下走。**
 
-**当前版本：0.7.7**
+换一个会话或换一个 AI 编程工具，你往往需要重新解释：任务进行到哪里、为什么这样设计、哪些方法已经试过。fluffy-context 把这些信息保存在项目里，在新任务开始时取出相关内容，交给 agent 使用。
 
-```text
-checkpoint → orient → compile → expand → feedback → Agent continues
-```
-
-`compile` 先返回有界的 summary 候选；Agent 只对需要的候选调用 `expand` 获取 structured 或 evidence 层。`feedback` 仍必须由调用方显式记录。
-
-`fluffy-context` 保存的是任务认知，不是项目代码备份。Git 仍是代码和文件变更的权威；Issue 系统、项目文档、`CLAUDE.md`、`AGENTS.md`、Skills 和 MCP 仍由各自系统维护。
-
-## 30 秒了解
-
-最常用的四类操作：
+它是 LLM 与项目之间的一层本地记忆：保存工作进度，积累经过验证的项目知识，按当前任务提供有长度预算的上下文。CLI 命令是 `ctx`，也提供 MCP 和 JavaScript / TypeScript API。
 
-- `ctx checkpoint`：保存进度、完成项、待办、决策、风险和关联文件。
-- `ctx orient`：只读恢复当前任务，并检索匹配的已验证 Knowledge、Deadend 和 open Note。
-- `ctx compile`：生成带预算、来源和排除原因的 provider-neutral Context Manifest。
-- `ctx learn` / `ctx deadend`：记录可复用结论和失败方案，之后显式验证再用于普通检索。
+> 本文对应 **1.0.0-beta.1**。稳定通道仍为 0.8.0；以下新工作流需要安装 beta。[升级说明与已知限制](CHANGELOG.md) · [1.0 后续计划](ROADMAP-1.0.md)
 
-## 0.7.7 当前能力与边界
+## 它能帮你做什么
 
-| 能力 | 当前支持 |
+| 你遇到的问题 | fluffy-context 的做法 |
 | --- | --- |
-| Context | 初始化、结构化 checkpoint、baseline/patch Snapshot、resume |
-| 检索 | `orient`、已验证 Knowledge/Deadend 检索、当前 Context 的 open Note |
-| Compiler | 确定性排序、字符预算、截断信息、provenance、纳入/排除原因 |
-| Manifest identity | `level`、`itemHash`、`manifestHash`、estimated token |
-| 文件活动 | 可选记录经过过滤的文件 metadata，并编译为 `activity` section |
-| Runtime | 本地 v2 Runtime、Git 观察、可选文件观察、自动唤醒和 fail-open 集成 |
-| 治理 | Knowledge/Deadend 的 candidate、verify、deprecate/obsolete、reject |
-| 集成 | Claude Code Hook、Claude Code 配置集成、MCP `context_orient`/`context_expand`/`context_usage_report`、TypeScript Agent API |
-| 观测 | `ctx usage report`：只读统计资产、显式复用、操作趋势和 estimated token 投入 |
-
-以下能力**不属于 0.7.7**：
-
-- 没有 `ctx clean`；`ctx usage report` 是当前支持的只读观测命令。
-- 不自动创建 checkpoint、Note、Knowledge 或 Deadend。
-- 不自动把 Candidate 提升为 Verified。
-- 不提供模型总结、Embedding/向量检索、远程同步、多人协作或 Context merge。
-
-0.7.7 已支持 `context_expand`，用于按需取得已选候选的 `structured` 或 `evidence` 层；它是无状态、只读操作，不读取项目文件内容，也不自动记录 feedback。
-
-## 快速开始
+| 新对话不知道上次做到哪里 | 保存进度、决策和待办，在下次任务开始时恢复 |
+| 不同 agent 重复探索同一个问题 | 将经过核验的结论和失败方案保存在项目中，供不同工具查询 |
+| 项目记忆散落在各种文档里 | 扫描已有 memory 和 agent 文档，去重后导入待核验知识 |
+| 把所有历史塞进 prompt 太长 | 按任务检索，在给定字符预算内返回相关上下文 |
+| 不知道保存的东西有没有用 | 查看知识、显式复用记录、日志体积和上下文成本估算 |
 
-### 1. 安装
+它适合持续维护的项目、跨会话的开发任务，以及多个 AI 工具交替使用的工作流。项目代码仍由 Git 管理；ctx 保存的是工作状态与项目知识。
 
-要求 Node.js `>=20.19.0`。Git 可选；在 Git 项目中，Runtime 会记录当前 branch、ref 和 commit 等 metadata。
+## 五分钟开始使用
 
-```bash
-npm install --global fluffy-context
-ctx --version
-```
-
-在源码工作树中开发时：
-
-```bash
-npm install
-npm run build
-npm install --global .
-```
-
-### 2. 初始化项目
+需要 **Node.js 20.19 或更高版本**。在终端安装，然后进入你的项目目录：
 
-在项目根目录运行：
-
-```bash
+```sh
+npm install --global fluffy-context@beta
+cd your-project
 ctx init
 ```
 
-也可以显式指定路径：
-
-```bash
-ctx init --path path/to/project
-```
-
-初始化会创建本地 `.context/` 存储和 `.contextignored` 规则文件。重复执行是幂等的，不会覆盖已有 Context 或忽略规则。
+`init` 会创建本地存储、迁移并校验旧数据、向 `AGENTS.md` 添加使用指引，并启动本地运行时。已有 `.claude` 目录时，还会配置 Claude Code 集成。重复执行会保留已有数据和禁用设置，不需要再逐条运行 migrate、verify、enable、start。
 
-### 3. 保存第一个工作状态
+### 1. 开始任务时，取得项目上下文
 
-```bash
-ctx checkpoint \
-  --title "支付回调修复" \
-  --progress "已定位签名校验失败原因" \
-  --completed "复现问题,确认失败边界" \
-  --pending "补充回归测试,运行集成测试" \
-  --decisions "在回调入口统一执行签名校验" \
-  --risks "第三方回调可能重复到达" \
-  --files "src/payment/callback.ts,test/payment/callback.test.ts"
+```sh
+ctx inject "修复支付回调重复处理的问题"
 ```
 
-第一次包含实际结构化内容的 checkpoint 会创建 baseline Snapshot；后续变化会创建 patch Snapshot。
+让 agent 执行这条命令，并读取返回的 `text`。它会包含相关的任务进度、已验证知识、失败方案和工作笔记。默认正文最多 2400 字符，需要时可以调整：
 
-- 内容没有变化时返回 `status: "no_change"`。
-- 默认两次实际写入之间至少间隔约 10 秒；变化过快时返回 `status: "rate_limited"` 和 `retryAt`。
-- 只有标题、没有实际结构化内容的 checkpoint 不会创建无意义 Snapshot。
-- `--last-error ""`、空列表等显式输入可以清理已有字段。
-
-查看当前状态：
-
-```bash
-ctx status
-ctx resume --max-chars 2000
+```sh
+ctx inject "修复支付回调重复处理的问题" --max-chars 4000
 ```
 
-### 4. 在下一次会话开始时恢复
+新项目还没有记忆，第一次返回内容很少是正常的。ctx 不会仅凭一次初始化就理解整个代码库。
 
-```bash
-ctx orient "支付回调签名校验" --max-chars 4000
-```
+### 2. 完成一个阶段后，留下进度
 
-不带查询时只恢复当前任务和 open Note：
+例如，你已经定位问题，但还没写完测试：
 
-```bash
-ctx orient
+```sh
+ctx checkpoint --title "支付回调修复" --progress "已定位重复回调导致重复扣款" --completed "复现问题,确认幂等键缺失" --pending "补充幂等处理,运行回归测试" --decisions "使用订单号和事件号作为幂等键"
 ```
 
-## 推荐工作流
-
-```text
-Orient → Plan → Implement → Verify → Handoff
-```
+下次换会话或换工具，再执行 `ctx inject "继续支付回调修复"`，agent 就能从保存的状态继续。
 
-1. **Orient**：开始任务时读取当前 Context 和已验证共识。
-2. **Plan**：先形成可执行的实现计划。
-3. **Implement**：遇到重要观察、阻塞或临时决策时记录 Note。
-4. **Verify**：运行适用的测试、构建或其他检查。
-5. **Handoff**：阶段结束时显式执行一次 checkpoint，记录完成项、待办、决策和风险。
+这些命令返回 JSON，方便 agent 和脚本读取。你也可以直接在终端使用。
 
-Hook 只提供有界、只读的阶段提示，不会自动创建 Note 或 checkpoint。Runtime 捕获文件和 Git metadata，也不能替代 Agent 主动记录任务认知。
+## 怎样接入你的 AI 编程工具
 
-## 核心命令
+接入后，理想的日常流程是：**任务开始取上下文 → 开发与验证 → 阶段结束存进度**。不需要人每轮对话都操作 ctx，但 agent 是否会触发取决于宿主的接入方式。
 
-### `ctx orient`
+### Claude Code
 
-`orient` 是新会话和新任务的快速恢复入口：
+项目已有 `.claude` 目录时，`ctx init` 会配置项目级 Hook 和 MCP。新项目也可以显式安装：
 
-```bash
-ctx orient "身份认证回调" \
-  --scope project \
-  --max-chars 4000 \
-  --knowledge-limit 5 \
-  --deadend-limit 5 \
-  --note-limit 10
+```sh
+ctx integrate claude install --apply
+ctx integrate claude inspect
 ```
 
-它返回：
+随后重启或重新连接 Claude Code。Hook 在会话开始和提交新任务时提供上下文；MCP 工具供 agent 按需查询、记录进度。这是当前提供自动注入的宿主适配器，真实宿主中的触发效果仍需 beta 验证。
 
-- 当前 Context 和 Snapshot 的有限 metadata；
-- 受字符预算限制的进度、错误、完成项、待办、决策、风险和关联文件；
-- 匹配且适用的已验证 Knowledge 和 Deadend；
-- 当前 Context 尚未吸收的 open Note；
-- v1/v2 选择方式、排除计数和截断说明。
+### 支持项目指引的 agent
 
-`orient` 是只读操作：不会创建 Snapshot、不会写入 Context、不会更新 `lastUsedAt`，也不会隐式记录 usage feedback。
+`ctx init` 写入的 `AGENTS.md` 指引会告诉 agent：新任务、上下文恢复或遇到新错误时调用 `ctx inject`，完成重要阶段后调用 `ctx checkpoint`。
 
-返回 `status: "no_context"` 表示项目已初始化，但还没有可恢复的有效 Context；这不是系统错误。
+宿主需要能读取项目指引并执行本地命令。这种方式依赖 agent 遵循指引，不保证每个工具都会自动触发。
 
-### `ctx compile`
+### 其它支持 MCP 的工具
 
-`compile` 面向需要结构化输入的 Agent、适配器和集成方，返回 provider-neutral JSON Manifest：
+在工具的 MCP 设置中添加一个本地 stdio 服务，命令为 `ctx`，参数为 `agent`、`serve`。例如，支持以下配置格式的客户端可以使用：
 
-```bash
-ctx compile "修复支付回调" --max-chars 4000
-ctx compile "验证签名逻辑" --scenario verification --paths src/payment/callback.ts
-ctx compile "查看最近修改" --activity-limit 10 --max-chars 4000
+```json
+{
+  "mcpServers": {
+    "fluffy-context": {
+      "command": "ctx",
+      "args": ["agent", "serve"]
+    }
+  }
+}
 ```
 
-Manifest 主要包含：
-
-- `intent`：规范化后的任务意图、场景、scope、paths 和预算；
-- `selected`：最终纳入的候选项；
-- `sections`：按 Context、Snapshot、Note、Knowledge、Deadend、Activity 等来源分组；
-- `excluded`：未纳入项目及其原因；
-- `provenance`：来源 Context、Snapshot、journal event 和读取状态；
-- `budget`：请求、使用、剩余字符和 section 统计；
-- `truncation`：预算或候选限制造成的截断说明；
-- `identity`：Manifest hash、选中 item hash 和 estimated token；
-- `text`：最终有界文本。
-
-0.7.7 的候选项提供：
-
-```text
-level: signal | summary | structured | evidence
-itemHash
- tokenEstimate
-expandable
-```
+将服务的工作目录设为项目目录，或在调用工具时传入项目的绝对 `path`。如果客户端找不到 `ctx`，使用其支持的绝对可执行路径配置方式。
 
-当前实际生成的候选项默认是 `summary` 层。`itemHash`、`manifestHash` 和 estimated token 可用于缓存、去重、审计和结果校验；token 是按字符估算的 provider-neutral 数值，不是真实 Provider 计费结果。
+先接入三个工具就能形成日常闭环：`context_inject` 取得上下文，`context_checkpoint` 保存进度，`context_import` 导入已有记忆。工具列表和输入参数由 MCP 服务提供。
 
-### `ctx expand`
+## 让工作经验变成可复用的知识
 
-`expand` 只接受本次 `compile` 返回的 selected candidate，并重新使用原始编译参数校验 `manifestHash`。调用方至少提供 `--candidate-id` 或 `--item-hash`，并选择 `--level structured|evidence`：
+进度回答“做到哪里了”，知识回答“下次遇到类似问题应该知道什么”。两者需要分别保存。
 
-```bash
-ctx compile "修复支付回调" --max-chars 4000 > manifest.json
-ctx expand --manifest-hash <manifestHash> --candidate-id <candidateId> \
-  --level structured --compile-max-chars 4000 --query "修复支付回调"
-```
+例如，你通过代码和测试确认了项目约束，可以记录结论及证据：
 
-`--compile-max-chars` 必须与原始 compile 的预算一致；`--max-chars` 是独立的展开输出预算。展开返回 `complete` 时包含完整 structured content，超过预算则返回有界文本、`content: null` 和 `status: partial`。它不缓存 Manifest、不写入 Context/journal/projection、不执行 usage feedback，也不读取文件正文、diff、命令或 stdout/stderr。
-
-Compiler 具有以下边界：
-
-- 相同输入得到确定性的排序、截断和 hash；
-- `maxChars` 使用 JavaScript UTF-16 字符串长度；
-- 不调用模型；
-- 不写入 Context 或 journal；
-- 普通查询默认只纳入适用且已验证的 Knowledge 和 Deadend；
-- `context_expand` 只读取已选候选的安全 metadata，不读取任意项目文件内容。
-
-### `ctx usage report`
-
-`usage report` 适合每周或每月复盘，不需要为每条 prompt 调用。它是只读的，基于 v1 文件和 v2 journal 派生统计，不创建事件、不修改 Context、Snapshot、Note 或 projection：
-
-```bash
-ctx usage report --days 30
-ctx usage report --month 2026-08 --granularity week
-ctx usage report --since 2026-08-01T00:00:00.000Z \
-  --until 2026-09-01T00:00:00.000Z \
-  --baseline-tokens 12000 --baseline-source manual
-ctx usage report --format ascii
+```sh
+ctx learn "支付回调必须在同一事务中写入幂等记录和更新订单状态" --evidence "src/payment/callback.ts,test/payment/callback.test.ts"
 ```
 
-默认输出稳定 JSON；`--format ascii` 仅输出终端仪表盘。报告展示资产总量和窗口增量、verified Knowledge/Deadend、显式 `record.used` reuse、orient/compile/expand/resume 操作统计、趋势以及上下文输出投入。
-
-报告中的 `chars / 4` 是 `estimated` token，不是真实 Provider token；Provider token 和计费金额当前为 `unavailable`。没有显式 `--baseline-tokens` 时，不会虚构 estimated savings、ROI 或 payback；查询命中、候选选择和编译纳入也不等于 reuse，只有显式 `record.used` 事件才计入复用。报告不替代 `ctx doctor`、`ctx journal verify` 或 Knowledge/Deadend 的人工治理。
-
-## Knowledge、Deadend 和 Note
-
-### Knowledge：记录可复用认知
+返回结果中会包含 `knowledgeId`。确认结论确实有依据后，将实际 ID 代入：
 
-```bash
-ctx learn "支付回调必须验证网关签名" \
-  --scope project \
-  --evidence "src/payment/callback.ts,回归测试"
-```
-
-新记录默认是 `candidate`，不会进入普通检索。确认后才会进入默认发现：
-
-```bash
+```sh
 ctx knowledge verify <knowledge-id>
-ctx knowledge discover "支付回调"
-```
-
-治理已有记录：
-
-```bash
-ctx knowledge deprecate <knowledge-id> --reason "已被新的签名校验流程取代"
-ctx knowledge reject <knowledge-id> --reason "证据不足"
-```
-
-普通 `orient` 和 `discover` 默认只使用 `verified` 且适用的 Knowledge。需要审查候选或其他状态时，使用 `--all` 或显式 `--status`。
-
-### Deadend：记录已验证不可行方案
-
-```bash
-ctx deadend \
-  --attempt "绕过回调签名验证" \
-  --reason "回归测试失败且会引入安全风险" \
-  --scope project \
-  --evidence "test/payment/callback.test.ts"
-```
-
-确认和治理：
-
-```bash
-ctx deadend verify <deadend-id>
-ctx deadend obsolete <deadend-id> --reason "当前架构已不再适用"
-ctx deadend reject <deadend-id> --reason "失败证据不足"
-```
-
-Deadend 默认也是 `candidate`；只有 `verified` Deadend 才会进入普通检索。终态记录会保留治理原因，但不会默认注入。
-
-### Note：低成本记录过程信息
-
-Note 不创建 Snapshot，适合开发过程中记录短期观察、问题、行动和决策：
-
-```bash
-ctx note add "测试环境缺少回调凭据" \
-  --kind problem \
-  --context <context-id>
-
-ctx note add "保留原始请求体后再执行验签" \
-  --kind decision \
-  --status resolved \
-  --context <context-id>
-```
-
-查看 Note 和只读 Activity：
-
-```bash
-ctx note list --context <context-id> --open
-ctx activity --context <context-id> --open
-```
-
-阶段性 checkpoint 可以显式吸收当前 Context 的 open Note：
-
-```bash
-ctx checkpoint \
-  --context <context-id> \
-  --progress "完成阶段排查" \
-  --absorb-notes
-```
-
-只有真正保存了新 Snapshot 时 Note 才会被标记为已吸收；`no_change` 和 `rate_limited` 不会改变 Note。
-
-## CLI 能力地图
-
-完整参数请使用 `ctx <command> --help`。常用命令按用途分组如下。
-
-### 日常使用
-
-| 命令 | 用途 |
-| --- | --- |
-| `ctx init` | 初始化 `.context/` |
-| `ctx checkpoint` | 保存 Context Snapshot |
-| `ctx resume` | 恢复完整 Context 详情 |
-| `ctx orient` | 读取有界任务上下文 |
-| `ctx compile` | 生成结构化 Context Manifest |
-| `ctx note add/list` | 记录和查看 Note |
-| `ctx activity` | 查看只读 Note/Snapshot 时间线 |
-| `ctx status` | 查看项目和 Context 索引 |
-| `ctx doctor` | 检查文件和 Snapshot 完整性 |
-
-### Knowledge 与 Deadend 治理
-
-```text
-ctx learn
-ctx knowledge
-ctx knowledge discover
-ctx knowledge verify
-ctx knowledge deprecate
-ctx knowledge reject
-ctx deadend
-ctx deadends
-ctx deadend verify
-ctx deadend obsolete
-ctx deadend reject
-ctx feedback use
-```
-
-`feedback use` 只记录显式的使用信号，用于确定性排序；不会改变 Knowledge/Deadend 的验证状态、confidence、证据或适用性。
-
-### 集成入口
-
-```text
-ctx integrate claude inspect
-ctx integrate claude install
-ctx integrate claude install --apply
-ctx hook claude-code session-start
-ctx hook claude-code user-prompt
-ctx agent serve
 ```
 
-### 高级维护
-
-```text
-ctx migrate v1 --dry-run
-ctx migrate v1 --apply
-ctx migrate verify
-ctx journal verify
-ctx runtime enable
-ctx runtime disable
-ctx runtime start
-ctx runtime stop
-ctx runtime status
-ctx filesystem enable
-ctx filesystem disable
-ctx filesystem status
-```
+此后，与支付回调相关的 `ctx inject` 才能把它作为已验证知识检索出来。`verify` 记录的是你或 agent 的核验决定，命令本身不会替你运行测试、证明结论。
 
-CLI 业务命令默认输出 JSON；`--help` 是面向终端用户的纯文本；错误写入 stderr 并返回非零退出码；`ctx --version` 输出 JSON 字符串。
+“越用越聪明”来自这个循环：**真实工作 → 留下证据 → 核验结论 → 后续任务复用**。当前版本不会自动训练模型，也不会把所有对话自动升级为可信知识。
 
-## 文件活动与 Runtime
+### 已经有 memory 或 agent 文档？
 
-文件观察默认关闭，需要显式开启：
+先预览将导入的内容：
 
-```bash
-ctx filesystem enable
-ctx filesystem status
-ctx filesystem disable
+```sh
+ctx import
 ```
 
-观察器只记录经过过滤的项目相对路径和有限 metadata，例如文件类型、大小和修改时间：
+检查后再保存：
 
-- 不记录文件内容、diff、命令或 stdout；
-- 使用与 Context 关联文件相同的 `.contextignored` 和内置保护规则；
-- `ctx compile` 的 `activity` 只表示“观察到文件发生变化”，不表示文件已被读取、理解或测试；
-- `--activity-limit 0` 只关闭单次编译中的 activity 候选，不改变监听策略；
-- v1 fallback 没有等价的文件活动来源，因此 activity section 可能为空。
-
-完成 v1 迁移并启用 Runtime 后，Runtime 会服务于当前项目的 v2 journal、Git 观察和可选文件观察。常用控制命令：
-
-```bash
-ctx runtime status
-ctx runtime enable
-ctx runtime start
-ctx runtime stop
-ctx runtime disable
+```sh
+ctx import --apply
+ctx knowledge --all
 ```
 
-已启用项目的 CLI Orient、MCP 和 Claude Hook 会尽力自动唤醒 Runtime；启动失败不会阻塞基础读取流程。`runtime disable` 会持久化关闭自动启动，直到再次执行 `runtime enable`。
-
-## Claude Code 集成
-
-先检查当前项目：
+支持项目内的 `memory/`、`.memory/`、`.claude/`、`.zcode/`、`.cursor/`、`.curcor/`、`.codex/`，以及 `AGENTS.md`、`CLAUDE.md`、`MEMORY.md`、`.cursorrules` 等文本来源。它会记录来源并去重；重复导入相同内容不会创建新知识。
 
-```bash
-ctx integrate claude inspect
-```
+导入的内容保持候选状态，核验后才进入普通检索。当前采用有限长度的文本行抽取，复杂多段结构可能需要人工整理。
 
-默认安装命令只输出预览，不写文件：
+## 查看它是否真的有用
 
-```bash
-ctx integrate claude install
-```
+使用易读的终端报告：
 
-确认后显式应用：
-
-```bash
-ctx integrate claude install --apply
+```sh
+ctx report --format ascii
 ```
 
-集成会幂等合并项目本地：
+报告展示已验证知识、显式复用记录、上下文输入/输出估算、日志体积和事件构成。需要程序处理时，使用默认返回 JSON 的 `ctx report`。
 
-- `.claude/settings.json`：`SessionStart` 和 `UserPromptSubmit` Hook；
-- `.mcp.json`：名为 `fluffy-context` 的 stdio MCP server。
+**检索到不等于采用，字符减少不等于模型账单减少。** 当前 token 使用字符数粗估，尚未接入模型提供商的实际用量；没有对照数据时，报告不能证明任务节省了多少 token 或时间。
 
-它会保留无关的 Hook、权限和 MCP server；遇到无效 JSON、无效结构或同名冲突时拒绝覆盖。Hook 是 fail-open 的只读提示，不会自动创建 checkpoint 或 Note。
+## 数据保存在什么地方
 
-## MCP 集成
+- 项目状态和知识保存在本地 `.context/`，核心检索不需要云服务或模型 API key。
+- `.contextignored` 用于配置要忽略的项目路径；默认过滤常见敏感文件。导入也会跳过疑似秘密行，但无法保证识别全部敏感内容，应用前应检查预览。
+- 初始化可能修改项目的 `AGENTS.md`；Claude 集成会修改 `.claude/settings.json` 和 `.mcp.json`。
+- 默认不开启文件监听。日志会分段压缩；可选观察有入库预算，但语义历史没有总容量硬上限。
 
-启动 MCP stdio server：
+CI 或不希望启动后台进程、写入宿主配置时，使用：
 
-```bash
-ctx agent serve
+```sh
+ctx init --no-start --no-integrations
 ```
 
-0.7.7 当前暴露以下工具：
-
-```text
-context_orient       只读、有界地获取任务上下文
-context_expand       只读地展开 selected compiler candidate
-context_compile      只读地生成确定性 Manifest
-context_resume       恢复 Context（可能更新 lastUsedAt）
-context_note_list    只读地列出 Note
-context_note_add     显式新增 Note
-context_checkpoint   显式保存 Context/Snapshot
-```
-
-输入字段与 CLI/Agent API 对齐：
-
-- `context_orient`：`path`、`contextId`、`query`、`scope`、`maxChars` 和各 source limit；
-- `context_compile`：编译选项及 `scenario`、`paths`、`activityLimit`、`trigger` 等字段；
-- `context_expand`：`manifestHash`、`candidateId` 或 `itemHash`、`level`、独立 `maxChars` 和原始 `compile` 参数；
-- `context_resume`：`contextId`、`maxChars`、`includeDetails`、`query`、`scope`；
-- `context_note_list`：`contextId`、`openOnly`、`limit`、`maxChars`；
-- `context_note_add`：必填 `message`，以及 Note 的 `kind`、`actor`、关联 Context/Snapshot、`relatedFiles` 和 `status`；
-- `context_checkpoint`：Context 输入字段、`absorbNotes` 和可选的 `lastError`。
+## 遇到问题
 
-成功调用同时返回 JSON `content` 和 `structuredContent`。结果分别对应 CLI/Agent API 的 Manifest、load result、Note 列表、单个 Note 或 checkpoint result。Checkpoint 保留 `saved`、`no_change` 和 `rate_limited` 状态，MCP 不自动重试，也不暴露绕过限流的参数。
-
-读写边界如下：
+| 情况 | 下一步 |
+| --- | --- |
+| 新项目没有可注入的内容 | 先保存一个真实 checkpoint，或导入并核验已有记忆 |
+| 导入后查询不到知识 | 用 `ctx knowledge --all` 查看候选；核验后再执行 verify |
+| agent 没有主动使用 ctx | 检查宿主是否加载项目指引、Hook 或 MCP；重连后确认工具可用 |
+| 找不到项目或需要检查存储 | 执行 `ctx status`、`ctx doctor`；在其它目录操作时传入 `--path` |
+| checkpoint 返回 `rate_limited` | 两次变化写入默认间隔至少 10 秒；到下一阶段再保存，避免循环重试 |
+| 想停止本地运行时 | 临时停止用 `ctx runtime stop`；持续禁用自动启动用 `ctx runtime disable` |
 
-- `context_orient`、`context_expand`、`context_compile` 和 `context_note_list` 是只读操作；
-- `context_resume` 使用现有 `loadContext` 语义，可能更新 `lastUsedAt`，但不会创建 Snapshot；
-- `context_note_add` 会写入 Note，但不会创建 Snapshot；
-- `context_checkpoint` 会创建或更新 Snapshot、Context metadata 和 index，并可显式吸收 Note；
-- 任何工具都不会自动创建 Knowledge、Deadend、feedback 或重复 checkpoint；
-- Knowledge/Deadend 的记录和治理暂不提供独立 MCP 工具，继续使用 CLI/Agent API。
+从 0.8.0 升级前，请先阅读[升级步骤](CHANGELOG.md#从-080-升级)：停止旧进程并备份 `.context`。新版压缩日志不能与 0.8.0 混用，升级全局包后也需要重启旧 MCP 连接。
 
-MCP 的 stdin/stdout 属于协议通道，不能混入日志或交互文本。调用错误（包括输入验证、缺失 Context、空 Note message 和 stale Manifest hash）返回单次工具错误，server 继续运行。`context_expand` 与 CLI/Agent API 使用相同的无状态 Manifest hash 校验和 partial 预算语义。
+完整参数可通过 `ctx --help`、`ctx <command> --help` 查看。`compile` / `expand` 等高级命令用于需要更多来源详情或自行构建 agent 集成的场景，不是首次使用的必做步骤。
 
-## TypeScript Agent API
+## 在代码中使用与参与开发
 
-使用公开包入口，不要导入内部 `dist/...` 路径，也不要直接读写 `.context`：
+自建 agent 可以通过 npm 包调用相同能力：
 
-```ts
-import {
-  contextOrient,
-  compileContext,
-  contextExpand,
-  saveContext,
-  loadContext,
-  searchContext,
-} from 'fluffy-context';
+```js
+import { injectContext } from 'fluffy-context';
 
-const orientation = await contextOrient(process.cwd(), {
-  query: 'payment callback',
+const context = await injectContext('/absolute/path/to/project', {
+  query: '修复支付回调重复处理的问题',
   maxChars: 2400,
 });
-
-const manifest = await compileContext(process.cwd(), {
-  query: 'payment callback',
-  maxChars: 4000,
-});
+console.log(context.text);
 ```
 
-`fluffy-context/agent` 提供相同的公开入口。当前主要 API 包括：
-
-```text
-contextOrient
-compileContext
-contextExpand
-saveContext
-loadContext
-searchContext
-recordContextUse
-```
-
-Compiler identity 工具也通过公开入口导出：
-
-```text
-canonicalJson
-contentHash
-estimateTokens
-rebuildManifestHash
-validateManifestIdentity
-```
-
-存储布局不是公开兼容性承诺；调用方应根据返回结果处理 `status`、预算、截断和 fallback 信息。
-
-## 安全与隐私边界
-
-### `.contextignored`
-
-`.contextignored` 使用接近 `.gitignore` 的规则排除不应作为关联文件保存的路径：
-
-```gitignore
-private/
-*.generated.ts
-notes/draft-*
-```
-
-内置保护规则优先于项目规则，不能通过否定规则绕过。默认排除包括：
-
-- `.context/`、`.git/`；
-- `node_modules/`、`dist/`、`build/`、`coverage/` 等依赖和构建目录；
-- `.env`、`.env.*`；
-- `*.pem`、`*.key`、`*.p12`、`*.pfx`；
-- 常见 credential、secret、token 文件；
-- 绝对路径和 `..` 越界路径。
+开发本项目：
 
-### 持久化边界
-
-- checkpoint、Note、Knowledge 和 Deadend 会保存用户显式提供的结构化任务文本；
-- 文件观察只保存过滤后的相对路径和 metadata，不保存内容或 diff；
-- Claude Hook 不保存原始 prompt，只在具备稳定标识时保存限长、脱敏后的 intent；
-- Runtime 仅绑定 `127.0.0.1`，使用项目本地能力令牌进行 IPC；令牌不会出现在状态输出或事件日志；
-- 集成、Runtime 或 v2 读取失败时，支持回退的宿主流程保持 fail-open。
-
-## v1 迁移
-
-已有 v1 `.context/` 数据时，先只读检查，再显式导入：
-
-```bash
-ctx migrate v1 --dry-run
-ctx migrate v1 --apply
-ctx migrate verify
-```
-
-- `--dry-run` 只检查，不创建 v2 数据；
-- `--apply` 才会追加 v1 provenance 事件；
-- 迁移不会重写或修复 v1 文件；
-- v1 与 v2 可以并存；
-- v2 不可用、损坏或尚未同步时，支持回退的读取接口继续使用 v1 行为；
-- `ctx journal verify` 可验证 v2 journal 的 hash chain 和记录完整性。
-
-## 常见问题
-
-### `ctx orient` 返回 `no_context`
-
-项目已初始化，但还没有包含实际内容的有效 checkpoint。运行：
-
-```bash
-ctx checkpoint --title "当前任务" --progress "记录当前进度"
-```
-
-### checkpoint 返回 `rate_limited`
-
-这是默认写入保护，不是保存损坏。查看返回的 `retryAt`，完成更多阶段工作后再保存，不要循环重试。
-
-### 为什么文件没有进入 Snapshot 的 `relatedFiles`
-
-先检查 `.contextignored` 和内置保护规则。敏感、构建、依赖、绝对路径和越界路径会被排除，即使使用否定规则也不能绕过。
-
-### Context 找不到怎么办
-
-确认当前项目路径和 Context ID，然后运行：
-
-```bash
-ctx status --path path/to/project
-ctx doctor --path path/to/project
-```
-
-Git branch/ref 漂移通常是提示，不等于 Context 被删除。
-
-### 为什么 `--help` 不能用 JSON.parse
-
-输出类型不同：
-
-- `ctx --help`：纯文本；
-- `ctx --version`：JSON 字符串；
-- 业务命令：格式化 JSON；
-- 错误：stderr 和非零退出码。
-
-### Windows 下从 Node 子进程调用 `ctx`
-
-交互式终端通常可以直接运行 `ctx`。从 Node `spawn` 或其他程序调用时，Windows npm 可能需要使用 `ctx.cmd`；不要把未经转义的用户输入拼接进 shell 命令。
-
-## 开发与验证
-
-```bash
-npm install
-npm run build
+```sh
+npm ci
 npm test
 npm run pack:check
-npm pack --dry-run --json
 ```
 
-发布包通过 `fluffy-context` 和 `fluffy-context/agent` 提供公开 Agent API，并包含 CLI、类型声明、README、LICENSE 和 `skills/fluffy-context/SKILL.md`。
-
-## 未来方向
-
-以下方向属于后续版本，不是 0.7.7 的当前能力：
-
-| 方向 | 目标 |
-| --- | --- |
-| Context expansion | 在现有 `context_expand` 基础上继续完善更丰富的分层内容 |
-| Decision Graph | 将决策变成可治理、可追溯的一等对象 |
-| Knowledge Evolution | 支持知识合并、替代、范围演化和 review-needed 信号 |
-| Journal maintenance | 提供安全的清理、归档和长期运行维护能力 |
-| Usage reporting | 统计估算 token、编译、展开、检索和反馈覆盖情况（`ctx report`） |
-| 外部协作 | 远程同步、多人协作和团队权限 |
-
-这些方向不会改变当前的边界：Git、项目文档和宿主规则继续由各自系统负责；Candidate 仍需要显式治理；模型调用和远程服务不是核心 Runtime 的隐式依赖。
-
-## License
-
-MIT
+本地全局验收使用 `npm run install:local`：构建 tarball、安装全局 ctx、核对文件哈希并保存安装回执。该命令会更新全局安装并初始化本仓库，不会发布到 npm。