fluffy-context 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fluffy_CX
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,6 @@
 # Context Runtime
 
-Context Runtime 是一个面向 AI 编程会话的本地上下文运行时 CLI。它把一次任务的进度、决策、待办、风险、知识和已验证死路保存为可恢复的结构化状态，帮助 Agent 在新会话中快速完成交接，而不是重新阅读大量项目内容。
+Context Runtime 是一个面向 AI 编程会话的本地上下文运行时 CLI。0.2.0 在可靠 Context 闭环之上增加了无模型、确定性的 Agent API 和 Knowledge Discovery，让 Agent 可以先发现已验证的项目共识，再保存和恢复工作状态，而不是每次重新阅读大量项目内容。
 
 它更接近“Context 的 Git”，而不是代码备份工具：Git 仍然负责代码和真实文件变更，Context Runtime 负责 AI 工作状态的版本化保存与恢复。
 
@@ -48,7 +48,8 @@ ctx init
 ├── contexts/
 ├── locks/
 ├── knowledge.json    # 首次使用 learn 后创建
-└── deadends.json     # 首次使用 deadend 后创建
+├── deadends.json     # 首次使用 deadend 后创建
+└── notes.json        # 首次使用 note add 后创建
 .contextignored
 ```
 
@@ -77,8 +78,28 @@ ctx resume
 ctx resume --max-chars 2000
 ```
 
+Agent 集成可以直接调用 `dist/src/agent/api.js` 中的 `saveContext`、`loadContext` 和 `searchContext`，不需要读取 `.context` 文件。推荐工作流是：先 `loadContext` 或 `ctx resume`，再用 `ctx knowledge discover` 或 `searchContext` 查找已验证共识，开发过程中记录 Note，阶段完成后 checkpoint，最后用 `learn` 和 `verify` 沉淀经过确认的知识。`loadContext` 默认不返回完整 details；候选 Knowledge、未验证 Deadend、模型推理、向量检索和远端服务不属于 0.2.0 默认能力。
+
+查看版本：
+
+```bash
+ctx --version
+```
+
 ## 常用命令
 
+所有一级命令都支持独立帮助，帮助输出为面向终端和 Agent 的纯文本，不会读取或修改项目状态：
+
+```bash
+ctx init --help
+ctx checkpoint --help
+ctx resume --help
+ctx knowledge verify --help
+ctx deadend verify --help
+```
+
+业务命令仍然默认输出 JSON；未知选项、缺少选项值和无效位置参数会以非零退出码报告。
+
 ### `ctx init`
 
 初始化项目的 Context Runtime 存储布局。重复执行是幂等的，不会覆盖已有 Context 或项目忽略规则。
@@ -106,7 +127,9 @@ ctx checkpoint \
   --files "src/payment/webhook.ts"
 ```
 
-列表参数使用逗号分隔。`--context` 省略时会创建新的 Context。默认情况下，实际保存之间至少间隔 10 秒；短时间内有变化的保存会返回 `rate_limited`，没有变化则返回 `no_change`。
+列表参数使用逗号分隔。`--context` 省略时会创建新的 Context。默认情况下，实际保存之间至少间隔 10 秒；短时间内有变化的保存会返回 `rate_limited`，没有变化则返回 `no_change`。使用 `--absorb-notes` 时，只有真正保存了新 Snapshot 才会将当前 Context 下尚未吸收的 Note 标记为已吸收；`no_change` 和 `rate_limited` 不会改变 Note。
+
+Checkpoint 会在写入前规范化新值：文本首尾空白会被移除，空白 `lastError` 会变成 `null`，列表中的空项会被移除。未提供字段会沿用已有值；显式传入空字符串或空列表会清除对应值。历史 Snapshot 不会被自动改写；`ctx doctor` 只负责报告历史数据损坏。
 
 ### `ctx resume`
 
@@ -146,16 +169,44 @@ ctx learn "订单取消后不能再次进入支付中状态" \
   --evidence "src/order/state-machine.ts,订单服务接口约束"
 ```
 
-查看和确认知识：
+查看、发现和确认知识：
 
 ```bash
 ctx knowledge
 ctx knowledge --all
+ctx knowledge discover "投保人认证"
+ctx knowledge discover "identity verification" --scope project --limit 10 --max-chars 4000
 ctx knowledge verify <knowledge-id>
 ```
 
+`discover` 默认只匹配已验证 Knowledge，返回命中的字段、匹配原因、来源 Context/Snapshot 和 supporting evidence。候选项不会参与普通发现；需要审查候选或其它状态时使用 `--all` 或 `--status candidate,verified`。匹配采用确定性的规范化文本和业务别名规则，不依赖模型或向量数据库。
+
 不提供 `--context` 时，知识仍可以记录为项目级候选知识；如果提供来源，则对应 Context 和 Snapshot 必须存在。
 
+### `ctx note`
+
+`ctx note` 是 Agent 在开发过程中记录短期问题、观察、行动和决策的低成本入口。它不会创建 Context Snapshot，记录会以追加方式保留，后续可由 checkpoint 显式吸收。
+
+```bash
+ctx note add "第三方人脸识别测试凭据缺失" \
+  --kind problem \
+  --context <context-id>
+ctx note add "保留原始请求体后验签恢复" \
+  --kind decision \
+  --status resolved \
+  --context <context-id>
+ctx note list --context <context-id> --open
+```
+
+### `ctx activity`
+
+`ctx activity` 面向人类查看 Agent 的开发活动，返回 Note 和已保存 Snapshot 的时间线。它是只读查询，不会创建额外事件日志。
+
+```bash
+ctx activity --context <context-id> --since 2026-08-21T00:00:00.000Z
+ctx activity --open --limit 20
+```
+
 ### `ctx deadend`
 
 记录一条已尝试但不可行的路径。Deadend 默认是 `candidate`，不会默认注入恢复摘要。

package/dist/src/agent/api.js

@@ -0,0 +1,133 @@
+import { readdir } from 'node:fs/promises';
+import { resolveProjectRoot } from '../project/project-resolver.js';
+import { contextsRoot, contextMetadataPath } from '../storage/layout.js';
+import { isRecord, readJson } from '../storage/json-store.js';
+import { checkpoint, rebuildSnapshot, resume } from '../runtime/runtime.js';
+import { discoverDeadends, discoverKnowledge, listDeadends } from '../runtime/knowledge.js';
+function normalized(value) {
+    return value.trim().toLocaleLowerCase();
+}
+function terms(query) {
+    return [...new Set(normalized(query).split(/\s+/).filter(Boolean))];
+}
+function limited(value, budget) {
+    if (budget.remaining <= 0)
+        return '';
+    const result = value.length <= budget.remaining ? value : `${value.slice(0, Math.max(0, budget.remaining - 1))}…`;
+    budget.remaining -= result.length;
+    return result;
+}
+function limitedList(values, budget) {
+    return values.flatMap((value) => {
+        if (budget.remaining <= 0)
+            return [];
+        const result = limited(value, budget);
+        return result ? [result] : [];
+    });
+}
+function summary(content, maxChars, branchOrCommitDrift = false) {
+    const budget = { remaining: Math.max(0, maxChars) };
+    return {
+        progressSummary: limited(content.progressSummary, budget),
+        lastError: content.lastError === null ? null : limited(content.lastError, budget),
+        completed: limitedList(content.completed, budget),
+        pendingTasks: limitedList(content.pendingTasks, budget),
+        decisions: limitedList(content.decisions, budget),
+        risks: limitedList(content.risks, budget),
+        relatedFiles: limitedList(content.relatedFiles, budget),
+        branchOrCommitDrift,
+    };
+}
+function isContextMetadata(value) {
+    return isRecord(value)
+        && value.schemaVersion === 1
+        && typeof value.id === 'string'
+        && typeof value.title === 'string'
+        && typeof value.projectRoot === 'string'
+        && (typeof value.currentSnapshotId === 'string' || value.currentSnapshotId === null)
+        && ['draft', 'active', 'stable', 'archived', 'deleted'].includes(value.status);
+}
+function matchedContext(context, content, queryTerms) {
+    const values = {
+        title: context.title,
+        progressSummary: content.progressSummary,
+        lastError: content.lastError ?? '',
+        completed: content.completed.join(' '),
+        pendingTasks: content.pendingTasks.join(' '),
+        decisions: content.decisions.join(' '),
+        risks: content.risks.join(' '),
+        relatedFiles: content.relatedFiles.join(' '),
+    };
+    const matchedFields = new Set();
+    const matchedTerms = new Set();
+    let score = 0;
+    for (const term of queryTerms) {
+        for (const [field, value] of Object.entries(values)) {
+            if (normalized(value).includes(term)) {
+                matchedFields.add(field);
+                matchedTerms.add(term);
+                score += field === 'title' ? 5 : 3;
+            }
+        }
+    }
+    return { matchedFields: [...matchedFields], matchedTerms: [...matchedTerms], score };
+}
+export async function saveContext(startPath, input, options = {}) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    return { projectRoot, result: await checkpoint(projectRoot, input, options) };
+}
+export async function loadContext(startPath, options = {}) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    const result = await resume(projectRoot, options.contextId, options.maxChars ?? 4000);
+    const knowledge = options.query === undefined ? null : await discoverKnowledge(projectRoot, options.query, { scope: options.scope, maxChars: options.maxChars ?? 4000 });
+    const verifiedDeadends = await listDeadends(projectRoot);
+    return {
+        projectRoot,
+        context: result.context,
+        snapshot: result.snapshot,
+        resumeSummary: result.resumeSummary,
+        ...(options.includeDetails ? { details: result.details } : {}),
+        knowledge,
+        verifiedDeadendIds: verifiedDeadends.map((item) => item.deadendId),
+    };
+}
+export async function searchContext(startPath, query, options = {}) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    const cleanQuery = query.trim();
+    if (!cleanQuery)
+        throw new Error('context search query must not be empty');
+    const queryTerms = terms(cleanQuery);
+    const contextIds = options.contextId ? [options.contextId] : await readdir(contextsRoot(projectRoot));
+    const matches = [];
+    for (const contextId of contextIds) {
+        const context = await readJson(contextMetadataPath(projectRoot, contextId), isContextMetadata);
+        if (!['active', 'stable'].includes(context.status) || !context.currentSnapshotId)
+            continue;
+        const content = await rebuildSnapshot(projectRoot, context.id, context.currentSnapshotId);
+        const match = matchedContext(context, content, queryTerms);
+        if (match.matchedTerms.length === 0)
+            continue;
+        matches.push({
+            context,
+            snapshotId: context.currentSnapshotId,
+            score: match.score,
+            matchedTerms: match.matchedTerms,
+            matchedFields: match.matchedFields,
+            summary: summary(content, options.maxChars ?? 4000),
+        });
+    }
+    matches.sort((left, right) => right.score - left.score || right.context.updatedAt.localeCompare(left.context.updatedAt) || left.context.id.localeCompare(right.context.id));
+    const limit = options.limit ?? 10;
+    const selected = matches.slice(0, limit);
+    const knowledge = await discoverKnowledge(projectRoot, cleanQuery, { scope: options.scope, maxChars: options.maxChars ?? 4000 });
+    const deadends = await discoverDeadends(projectRoot, cleanQuery, { scope: options.scope, maxChars: options.maxChars ?? 4000 });
+    return {
+        projectRoot,
+        query: cleanQuery,
+        total: matches.length,
+        truncated: matches.length > selected.length,
+        hits: selected,
+        knowledge,
+        verifiedDeadendIds: deadends.hits.map((hit) => hit.deadend.deadendId),
+    };
+}

package/dist/src/agent/index.js

@@ -0,0 +1 @@
+export * from './api.js';

package/dist/src/cli/main.js

@@ -2,31 +2,27 @@
 import { checkpoint, resume } from '../runtime/runtime.js';
 import { doctor, status } from '../runtime/diagnostics.js';
 import { initProject } from '../runtime/init.js';
-import { learnKnowledge, listKnowledge, verifyKnowledge, recordDeadend, listDeadends, verifyDeadend } from '../runtime/knowledge.js';
+import { discoverKnowledge, learnKnowledge, listKnowledge, verifyKnowledge, recordDeadend, listDeadends, verifyDeadend } from '../runtime/knowledge.js';
+import { addNote, listActivity, listNotes } from '../runtime/notes.js';
+import { VERSION } from '../version.js';
 function option(args, name) {
     const index = args.indexOf(name);
     if (index < 0)
         return undefined;
     const value = args[index + 1];
-    if (!value || value.startsWith('--'))
+    if (value === undefined || value.startsWith('--'))
         throw new Error(`missing value for ${name}`);
     return value;
 }
-function required(args, name) {
-    const value = option(args, name);
-    if (!value)
-        throw new Error(`missing required option ${name}`);
-    return value;
-}
 function listOption(args, name) {
     const value = option(args, name);
-    return value ? value.split(',').map((item) => item.trim()).filter(Boolean) : undefined;
+    return value === undefined ? undefined : value.split(',').map((item) => item.trim()).filter(Boolean);
 }
-function positionals(args, options) {
+function positionals(args, valueOptions) {
     const values = [];
     for (let index = 0; index < args.length; index += 1) {
-        if (args[index].startsWith('--') || args[index] === '-m') {
-            if (options.includes(args[index]))
+        if (args[index].startsWith('-')) {
+            if (valueOptions.includes(args[index]))
                 index += 1;
             continue;
         }
@@ -34,15 +30,19 @@ function positionals(args, options) {
     }
     return values;
 }
-function validateOptions(args, allowed) {
+function validateOptions(args, allowed, valueOptions = []) {
     for (let index = 0; index < args.length; index += 1) {
         const argument = args[index];
         if (!argument.startsWith('-'))
             continue;
         if (!allowed.includes(argument))
             throw new Error(`unknown option ${argument}`);
-        if (argument !== '--all' && argument !== '--help' && argument !== '--version')
+        if (valueOptions.includes(argument)) {
+            const value = args[index + 1];
+            if (value === undefined || value.startsWith('-'))
+                throw new Error(`missing value for ${argument}`);
             index += 1;
+        }
     }
 }
 function numericOption(args, name, defaultValue) {
@@ -54,33 +54,203 @@ function numericOption(args, name, defaultValue) {
         throw new Error(`${name} must be a non-negative integer`);
     return parsed;
 }
+function enumOption(args, name, values) {
+    const value = option(args, name);
+    if (value === undefined)
+        return undefined;
+    if (!values.includes(value))
+        throw new Error(`${name} must be one of: ${values.join(', ')}`);
+    return value;
+}
+const HELP = {
+    init: `usage: ctx init [path] [--path <path>]
+
+Initialize the local .context runtime layout. Re-running init is safe.
+
+Options:
+  --path <path>  Project path`,
+    checkpoint: `usage: ctx checkpoint [options]
+
+Save structured work state as a baseline or incremental snapshot.
+
+Options:
+  --path <path>          Project path
+  --context <id>         Existing context ID
+  --title <text>         Context title
+  --progress <text>      Current progress summary
+  --last-error <text>    Last error (blank clears it)
+  --completed <items>    Comma-separated completed items
+  --pending <items>      Comma-separated pending tasks
+  --decisions <items>    Comma-separated decisions
+  --risks <items>        Comma-separated risks
+  --files <paths>        Comma-separated related paths
+  --absorb-notes         Mark open notes for this context as absorbed`,
+    resume: `usage: ctx resume [options]
+
+Resume the most relevant active or stable context.
+
+Options:
+  --path <path>          Project path
+  --context <id>         Context ID
+  --max-chars <number>   Maximum summary characters`,
+    status: `usage: ctx status [--path <path>]
+
+Show the initialized project and context index.`,
+    doctor: `usage: ctx doctor [--path <path>]
+
+Check runtime files and snapshot integrity without modifying them.`,
+    learn: `usage: ctx learn <statement> [options]
+
+Record a candidate project knowledge item.
+
+Options:
+  --path <path>          Project path
+  --kind <kind>          Knowledge kind
+  --scope <scope>        Knowledge scope
+  --context <id>         Source context ID
+  --snapshot <id>        Source snapshot ID
+  --evidence <items>     Comma-separated evidence references`,
+    knowledge: `usage: ctx knowledge [--all] [--path <path>]
+       ctx knowledge verify <knowledge-id> [--path <path>]
+       ctx knowledge discover <query> [options]
+
+List candidate/verified knowledge, verify one item, or discover matching knowledge.
+
+Options:
+  --all                  Include unverified items
+  --path <path>          Project path`,
+    'knowledge verify': `usage: ctx knowledge verify <knowledge-id> [--path <path>]
+
+Mark a knowledge item as verified.`,
+    'knowledge discover': `usage: ctx knowledge discover <query> [options]
+
+Find matching project knowledge using deterministic lexical and alias rules.
+
+Options:
+  --path <path>          Project path
+  --scope <scope>        Exact knowledge scope
+  --status <statuses>    Comma-separated candidate/verified/deprecated/rejected
+  --all                  Include all knowledge statuses
+  --limit <number>       Maximum matches (default: 10)
+  --max-chars <number>   Maximum text characters per match`,
+    deadend: `usage: ctx deadend [attempt] [options]
+       ctx deadend verify <deadend-id> [--path <path>]
+
+Record or verify a candidate deadend.
+
+Options:
+  --path <path>          Project path
+  --attempt <text>       Attempt description
+  --reason <text>        Why it failed
+  -m <text>              Alias for --reason
+  --scope <scope>        Deadend scope
+  --context <id>         Source context ID
+  --snapshot <id>        Source snapshot ID
+  --evidence <items>     Comma-separated evidence references`,
+    'deadend verify': `usage: ctx deadend verify <deadend-id> [--path <path>]
+
+Mark a deadend as verified.`,
+    deadends: `usage: ctx deadends [--all] [--path <path>]
+
+List recorded deadends.`,
+    note: `usage: ctx note add <message> [options]
+       ctx note list [options]
+
+Agent-facing short-term notes for problems, actions, observations, and decisions.
+
+Run \"ctx note add --help\" or \"ctx note list --help\" for details.`,
+    'note add': `usage: ctx note add <message> [options]
+
+Append a short note without creating a Context Snapshot.
+
+Options:
+  --path <path>          Project path
+  --kind <kind>          problem|action|observation|decision
+  --context <id>         Context ID
+  --snapshot <id>        Snapshot ID
+  --files <paths>        Comma-separated related paths
+  --actor <actor>        agent|human
+  --status <status>      open|resolved`,
+    'note list': `usage: ctx note list [options]
+
+List recent notes for an Agent or integration.
+
+Options:
+  --path <path>          Project path
+  --context <id>         Context ID
+  --open                 Only unresolved and unabsorbed notes
+  --limit <number>       Maximum notes (default: 50)
+  --max-chars <number>   Maximum message characters`,
+    activity: `usage: ctx activity [options]
+
+Show a Human-oriented timeline of notes and saved checkpoints.
+
+Options:
+  --path <path>          Project path
+  --context <id>         Context ID
+  --since <ISO>          Only activity at or after this time
+  --open                 Only open notes
+  --limit <number>       Maximum items (default: 50)
+  --max-chars <number>   Maximum message characters`,
+};
 function usage() {
-    return 'usage: ctx init|checkpoint|resume|status|doctor|learn|knowledge|deadend|deadends [options]';
+    return `usage: ctx init|checkpoint|resume|status|doctor|learn|knowledge|deadend|deadends|note|activity [options]
+
+Run \"ctx <command> --help\" for command details.`;
 }
 function print(value) {
     process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 }
+function printHelp(args) {
+    const command = args[0];
+    if (!command) {
+        process.stdout.write(`${usage()}\n`);
+        return true;
+    }
+    const key = args[1] === 'verify' || args[1] === 'add' || args[1] === 'list' || args[1] === 'discover' ? `${command} ${args[1]}` : command;
+    const help = HELP[key];
+    if (!help)
+        return false;
+    if (args.includes('--help')) {
+        process.stdout.write(`${help}\n`);
+        return true;
+    }
+    return false;
+}
+function validatePositionals(values, max, usageText) {
+    if (values.length > max)
+        throw new Error(usageText);
+}
 async function run(args) {
     if (args.includes('--version')) {
-        print('0.1.0');
+        print(VERSION);
         return;
     }
-    if (args.length === 0 || args.includes('--help')) {
-        process.stdout.write(`${usage()}\n`);
+    if (args.length === 0 || args[0] === '--help') {
+        printHelp([]);
         return;
     }
+    if (args.includes('--help') && printHelp(args))
+        return;
     const command = args[0];
     const target = option(args, '--path');
     switch (command) {
-        case 'init':
-            print(await initProject(target ?? args[1]));
+        case 'init': {
+            validateOptions(args.slice(1), ['--path'], ['--path']);
+            const values = positionals(args.slice(1), ['--path']);
+            validatePositionals(values, 1, HELP.init);
+            print(await initProject(target ?? values[0]));
             return;
+        }
         case 'checkpoint': {
+            validateOptions(args.slice(1), ['--path', '--context', '--title', '--progress', '--last-error', '--completed', '--pending', '--decisions', '--risks', '--files', '--absorb-notes'], ['--path', '--context', '--title', '--progress', '--last-error', '--completed', '--pending', '--decisions', '--risks', '--files']);
+            validatePositionals(positionals(args.slice(1), ['--path', '--context', '--title', '--progress', '--last-error', '--completed', '--pending', '--decisions', '--risks', '--files']), 0, HELP.checkpoint);
             const input = {
                 contextId: option(args, '--context'),
+                absorbNotes: args.includes('--absorb-notes'),
                 title: option(args, '--title'),
                 progressSummary: option(args, '--progress'),
-                lastError: option(args, '--last-error') ?? null,
+                lastError: option(args, '--last-error'),
                 completed: listOption(args, '--completed'),
                 pendingTasks: listOption(args, '--pending'),
                 decisions: listOption(args, '--decisions'),
@@ -91,18 +261,28 @@ async function run(args) {
             return;
         }
         case 'resume':
-            validateOptions(args.slice(1), ['--path', '--context', '--max-chars']);
+            validateOptions(args.slice(1), ['--path', '--context', '--max-chars'], ['--path', '--context', '--max-chars']);
+            validatePositionals(positionals(args.slice(1), ['--path', '--context', '--max-chars']), 0, HELP.resume);
             print(await resume(target, option(args, '--context'), numericOption(args, '--max-chars', 4000)));
             return;
         case 'status':
+            validateOptions(args.slice(1), ['--path'], ['--path']);
+            validatePositionals(positionals(args.slice(1), ['--path']), 0, HELP.status);
             print(await status(target));
             return;
         case 'doctor':
+            validateOptions(args.slice(1), ['--path'], ['--path']);
+            validatePositionals(positionals(args.slice(1), ['--path']), 0, HELP.doctor);
             print(await doctor(target));
             return;
         case 'learn': {
-            const statement = positionals(args.slice(1), ['--path', '--scope', '--context', '--snapshot', '--evidence']);
+            const valueOptions = ['--path', '--kind', '--scope', '--context', '--snapshot', '--evidence'];
+            validateOptions(args.slice(1), valueOptions, valueOptions);
+            const statement = positionals(args.slice(1), valueOptions);
+            if (statement.length === 0)
+                throw new Error(HELP.learn);
             const input = {
+                kind: option(args, '--kind'),
                 scope: option(args, '--scope'),
                 sourceContextId: option(args, '--context'),
                 sourceSnapshotId: option(args, '--snapshot'),
@@ -111,26 +291,104 @@ async function run(args) {
             print(await learnKnowledge(target, statement.join(' '), input));
             return;
         }
-        case 'knowledge':
-            if (args[1] === 'verify')
-                print(await verifyKnowledge(target, args[2]));
-            else
+        case 'note': {
+            if (args[1] === 'add') {
+                const valueOptions = ['--path', '--kind', '--context', '--snapshot', '--files', '--actor', '--status'];
+                validateOptions(args.slice(2), valueOptions, valueOptions);
+                const values = positionals(args.slice(2), valueOptions);
+                if (values.length === 0)
+                    throw new Error(HELP['note add']);
+                const input = {
+                    kind: enumOption(args, '--kind', ['problem', 'action', 'observation', 'decision']),
+                    actor: enumOption(args, '--actor', ['agent', 'human']),
+                    contextId: option(args, '--context'),
+                    snapshotId: option(args, '--snapshot'),
+                    relatedFiles: listOption(args, '--files'),
+                    status: enumOption(args, '--status', ['open', 'resolved']),
+                };
+                print(await addNote(target, values.join(' '), input));
+            }
+            else if (args[1] === 'list') {
+                const valueOptions = ['--path', '--context', '--limit', '--max-chars'];
+                validateOptions(args.slice(2), [...valueOptions, '--open'], valueOptions);
+                validatePositionals(positionals(args.slice(2), valueOptions), 0, HELP['note list']);
+                print(await listNotes(target, { contextId: option(args, '--context'), openOnly: args.includes('--open'), limit: numericOption(args, '--limit', 50), maxChars: numericOption(args, '--max-chars', 500) }));
+            }
+            else {
+                throw new Error(HELP.note);
+            }
+            return;
+        }
+        case 'activity': {
+            const valueOptions = ['--path', '--context', '--since', '--limit', '--max-chars'];
+            validateOptions(args.slice(1), [...valueOptions, '--open'], valueOptions);
+            validatePositionals(positionals(args.slice(1), valueOptions), 0, HELP.activity);
+            const query = {
+                contextId: option(args, '--context'),
+                since: option(args, '--since'),
+                openOnly: args.includes('--open'),
+                limit: numericOption(args, '--limit', 50),
+                maxChars: numericOption(args, '--max-chars', 500),
+            };
+            print(await listActivity(target, query));
+            return;
+        }
+        case 'knowledge': {
+            if (args[1] === 'discover') {
+                const valueOptions = ['--path', '--scope', '--status', '--limit', '--max-chars'];
+                validateOptions(args.slice(2), [...valueOptions, '--all'], valueOptions);
+                const query = positionals(args.slice(2), valueOptions);
+                if (query.length === 0)
+                    throw new Error(HELP['knowledge discover']);
+                const statuses = args.includes('--all') ? ['candidate', 'verified', 'deprecated', 'rejected'] : (listOption(args, '--status') ?? ['verified']);
+                if (statuses.some((status) => !['candidate', 'verified', 'deprecated', 'rejected'].includes(status)))
+                    throw new Error('--status contains an invalid knowledge status');
+                print(await discoverKnowledge(target, query.join(' '), {
+                    scope: option(args, '--scope'),
+                    statuses: statuses,
+                    limit: numericOption(args, '--limit', 10),
+                    maxChars: numericOption(args, '--max-chars', 4000),
+                }));
+            }
+            else if (args[1] === 'verify') {
+                validateOptions(args.slice(2), ['--path'], ['--path']);
+                const values = positionals(args.slice(2), ['--path']);
+                if (values.length !== 1)
+                    throw new Error(HELP['knowledge verify']);
+                print(await verifyKnowledge(target, values[0]));
+            }
+            else {
+                validateOptions(args.slice(1), ['--all', '--path'], ['--path']);
+                validatePositionals(positionals(args.slice(1), ['--path']), 0, HELP.knowledge);
                 print(await listKnowledge(target, args.includes('--all')));
+            }
             return;
+        }
         case 'deadend':
-            if (args[1] === 'verify')
-                print(await verifyDeadend(target, args[2]));
+            if (args[1] === 'verify') {
+                validateOptions(args.slice(2), ['--path'], ['--path']);
+                const values = positionals(args.slice(2), ['--path']);
+                if (values.length !== 1)
+                    throw new Error(HELP['deadend verify']);
+                print(await verifyDeadend(target, values[0]));
+            }
             else {
+                const valueOptions = ['--path', '--attempt', '--reason', '-m', '--scope', '--context', '--snapshot', '--evidence'];
+                validateOptions(args.slice(1), valueOptions, valueOptions);
+                const values = positionals(args.slice(1), valueOptions);
+                validatePositionals(values, 1, HELP.deadend);
                 const input = {
                     scope: option(args, '--scope'),
                     sourceContextId: option(args, '--context'),
                     sourceSnapshotId: option(args, '--snapshot'),
                     evidence: listOption(args, '--evidence'),
                 };
-                print(await recordDeadend(target, option(args, '--attempt') ?? args[1], option(args, '--reason') ?? option(args, '-m') ?? '', input));
+                print(await recordDeadend(target, option(args, '--attempt') ?? values[0], option(args, '--reason') ?? option(args, '-m') ?? '', input));
             }
             return;
         case 'deadends':
+            validateOptions(args.slice(1), ['--all', '--path'], ['--path']);
+            validatePositionals(positionals(args.slice(1), ['--path']), 0, HELP.deadends);
             print(await listDeadends(target, args.includes('--all')));
             return;
         default:

package/dist/src/runtime/diagnostics.js

@@ -1,8 +1,10 @@
 import { access, readdir } from 'node:fs/promises';
 import { resolveProjectRoot } from '../project/project-resolver.js';
 import { readJson } from '../storage/json-store.js';
-import { contextRoot, contextMetadataPath, contextsRoot, indexPath, manifestPath, snapshotPath } from '../storage/layout.js';
-import { rebuildIndex } from './runtime.js';
+import { contextRoot, contextMetadataPath, contextsRoot, indexPath, manifestPath, notesPath, snapshotPath } from '../storage/layout.js';
+import { rebuildIndex, rebuildSnapshot } from './runtime.js';
+import { isValidNote } from './notes.js';
+import { filterPaths } from '../capture/context-filter.js';
 export async function status(startPath) {
     const projectRoot = await resolveProjectRoot(startPath);
     try {
@@ -50,15 +52,42 @@ export async function doctor(startPath) {
         const entries = await readdir(contextsRoot(projectRoot));
         for (const contextId of entries) {
             const context = await readJson(contextMetadataPath(projectRoot, contextId));
-            if (context.id !== contextId || context.schemaVersion !== 1)
+            if (context.id !== contextId || context.schemaVersion !== 1 || typeof context.title !== 'string' || typeof context.projectRoot !== 'string' || typeof context.updatedAt !== 'string') {
                 throw new Error(`invalid context ${contextId}`);
-            if (context.currentSnapshotId)
+            }
+            if (context.currentSnapshotId) {
                 await access(snapshotPath(projectRoot, contextId, context.currentSnapshotId));
+                await rebuildSnapshot(projectRoot, contextId, context.currentSnapshotId);
+            }
+        }
+    });
+    await check('notes', async () => {
+        try {
+            const notes = await readJson(notesPath(projectRoot));
+            if (notes.schemaVersion !== 1 || !Array.isArray(notes.items) || notes.items.some((note) => !isValidNote(note)))
+                throw new Error('invalid notes');
+            const ids = new Set(notes.items.map((note) => note.noteId));
+            if (ids.size !== notes.items.length)
+                throw new Error('duplicate note id');
+            const contextIds = new Set((await readdir(contextsRoot(projectRoot))).filter((entry) => entry.startsWith('ctx-')));
+            for (const note of notes.items) {
+                if (note.contextId && !contextIds.has(note.contextId))
+                    throw new Error(`note ${note.noteId} references missing context`);
+                if (note.relatedFiles.length !== (await filterPaths(projectRoot, note.relatedFiles)).length)
+                    throw new Error(`note ${note.noteId} contains filtered paths`);
+                if (note.snapshotId && note.contextId)
+                    await access(snapshotPath(projectRoot, note.contextId, note.snapshotId));
+            }
+        }
+        catch (error) {
+            if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+                return;
+            throw error;
         }
     });
     await check('index rebuild', async () => {
         const stored = await readJson(indexPath(projectRoot));
-        const rebuilt = await rebuildIndex(projectRoot);
+        const rebuilt = await rebuildIndex(projectRoot, false);
         const rebuiltIds = new Set(rebuilt.contexts.map((entry) => entry.contextId));
         const storedIds = new Set(stored.contexts.map((entry) => entry.contextId));
         if (rebuiltIds.size !== rebuilt.contexts.length || storedIds.size !== stored.contexts.length)

package/dist/src/runtime/knowledge.js

@@ -1,30 +1,73 @@
 import crypto from 'node:crypto';
-import { access } from 'node:fs/promises';
 import { resolveProjectRoot } from '../project/project-resolver.js';
 import { atomicWriteJson } from '../storage/atomic-write.js';
 import { isRecord, readJson } from '../storage/json-store.js';
 import { withLock } from '../storage/lock.js';
 import { contextMetadataPath, deadendsPath, knowledgePath, locksDirectory, snapshotPath } from '../storage/layout.js';
+import { rebuildSnapshot } from './runtime.js';
 function id(prefix) {
     return `${prefix}-${Date.now().toString(36)}-${crypto.randomBytes(4).toString('hex')}`;
 }
 function isNotFound(error) {
     return typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT';
 }
+function isKnowledge(value) {
+    return isRecord(value)
+        && typeof value.knowledgeId === 'string'
+        && typeof value.kind === 'string' && value.kind.trim().length > 0
+        && typeof value.statement === 'string' && value.statement.trim().length > 0
+        && typeof value.scope === 'string' && value.scope.trim().length > 0
+        && typeof value.confidence === 'number' && value.confidence >= 0 && value.confidence <= 1
+        && ['candidate', 'verified', 'deprecated', 'rejected'].includes(value.status)
+        && Array.isArray(value.sourceContextIds) && value.sourceContextIds.every((item) => typeof item === 'string')
+        && Array.isArray(value.sourceSnapshotIds) && value.sourceSnapshotIds.every((item) => typeof item === 'string')
+        && Array.isArray(value.supportingEvidence) && value.supportingEvidence.every((item) => typeof item === 'string')
+        && typeof value.createdAt === 'string'
+        && typeof value.updatedAt === 'string';
+}
 function isKnowledgeFile(value) {
-    return isRecord(value) && value.schemaVersion === 1 && Array.isArray(value.items);
+    if (!isRecord(value) || value.schemaVersion !== 1 || !Array.isArray(value.items) || !value.items.every(isKnowledge))
+        return false;
+    const ids = value.items.map((item) => item.knowledgeId);
+    return new Set(ids).size === ids.length;
+}
+function cleanList(values) {
+    return [...new Set((values ?? []).map((value) => value.trim()).filter(Boolean))];
+}
+function normalized(value) {
+    return value.trim().toLocaleLowerCase();
+}
+function isDeadend(value) {
+    return isRecord(value)
+        && typeof value.deadendId === 'string'
+        && typeof value.attempt === 'string'
+        && typeof value.reason === 'string'
+        && Array.isArray(value.observedEvidence) && value.observedEvidence.every((item) => typeof item === 'string')
+        && typeof value.scope === 'string'
+        && ['candidate', 'verified', 'obsolete', 'rejected'].includes(value.status)
+        && (typeof value.sourceContextId === 'string' || value.sourceContextId === null)
+        && (typeof value.sourceSnapshotId === 'string' || value.sourceSnapshotId === null)
+        && typeof value.createdAt === 'string'
+        && typeof value.updatedAt === 'string';
 }
 function isDeadendFile(value) {
-    return isRecord(value) && value.schemaVersion === 1 && Array.isArray(value.items);
+    if (!isRecord(value) || value.schemaVersion !== 1 || !Array.isArray(value.items) || !value.items.every(isDeadend))
+        return false;
+    const ids = value.items.map((item) => item.deadendId);
+    return new Set(ids).size === ids.length;
 }
 async function validateSource(projectRoot, contextId, snapshotId) {
     if (!contextId && snapshotId)
         throw new Error('source snapshot requires source context');
     if (!contextId)
         return;
-    await access(contextMetadataPath(projectRoot, contextId));
-    if (snapshotId)
-        await access(snapshotPath(projectRoot, contextId, snapshotId));
+    const context = await readJson(contextMetadataPath(projectRoot, contextId), (value) => isRecord(value) && value.id === contextId && value.schemaVersion === 1);
+    if (snapshotId) {
+        const snapshot = await readJson(snapshotPath(projectRoot, contextId, snapshotId), (value) => isRecord(value) && value.snapshotId === snapshotId && value.contextId === contextId && value.schemaVersion === 1);
+        await rebuildSnapshot(projectRoot, contextId, snapshot.snapshotId);
+    }
+    if (context.projectRoot !== projectRoot)
+        throw new Error(`source context belongs to another project: ${contextId}`);
 }
 async function loadKnowledge(projectRoot) {
     try {
@@ -49,20 +92,29 @@ async function loadDeadends(projectRoot) {
 export async function learnKnowledge(startPath, statement, scopeOrInput = 'project') {
     const projectRoot = await resolveProjectRoot(startPath);
     const input = typeof scopeOrInput === 'string' ? { scope: scopeOrInput } : scopeOrInput;
+    const cleanStatement = statement.trim();
+    const cleanScope = (input.scope ?? 'project').trim();
+    const cleanKind = (input.kind ?? 'fact').trim();
+    if (!cleanStatement)
+        throw new Error('knowledge statement must not be empty');
+    if (!cleanScope)
+        throw new Error('knowledge scope must not be empty');
+    if (!cleanKind)
+        throw new Error('knowledge kind must not be empty');
     await validateSource(projectRoot, input.sourceContextId, input.sourceSnapshotId);
     return withLock(`${locksDirectory(projectRoot)}/knowledge.lock`, async () => {
         const file = await loadKnowledge(projectRoot);
         const now = new Date().toISOString();
         const item = {
             knowledgeId: id('know'),
-            kind: 'fact',
-            statement,
-            scope: input.scope ?? 'project',
+            kind: cleanKind,
+            statement: cleanStatement,
+            scope: cleanScope,
             confidence: 0.5,
             status: 'candidate',
-            sourceContextIds: input.sourceContextId ? [input.sourceContextId] : [],
-            sourceSnapshotIds: input.sourceSnapshotId ? [input.sourceSnapshotId] : [],
-            supportingEvidence: input.evidence ?? [],
+            sourceContextIds: cleanList(input.sourceContextId ? [input.sourceContextId] : []),
+            sourceSnapshotIds: cleanList(input.sourceSnapshotId ? [input.sourceSnapshotId] : []),
+            supportingEvidence: cleanList(input.evidence),
             createdAt: now,
             updatedAt: now,
         };
@@ -75,6 +127,78 @@ export async function listKnowledge(startPath, includeUnverified = false) {
     const file = await loadKnowledge(projectRoot);
     return includeUnverified ? file.items : file.items.filter((item) => item.status === 'verified');
 }
+const aliasGroups = [
+    ['投保人认证', '投保人身份认证', '身份核验', '实名认证', 'applicant authentication', 'identity verification'],
+    ['短信验证码', '验证码', 'sms verification', 'otp'],
+    ['证件ocr', '证件识别', 'identity ocr', 'document ocr'],
+    ['人脸识别', '人脸认证', 'face recognition', 'facial verification'],
+];
+function queryTerms(query) {
+    const normalizedQuery = normalized(query);
+    const terms = new Set(normalizedQuery.split(/\s+/).filter(Boolean));
+    for (const group of aliasGroups) {
+        if (group.some((alias) => normalizedQuery.includes(normalized(alias)))) {
+            for (const alias of group)
+                terms.add(normalized(alias));
+        }
+    }
+    return [...terms];
+}
+function matchedFields(knowledge, terms) {
+    const values = { statement: normalized(knowledge.statement), kind: normalized(knowledge.kind), scope: normalized(knowledge.scope) };
+    const fields = new Set();
+    const matched = new Set();
+    let score = 0;
+    const normalizedQuery = terms.join(' ');
+    if (values.statement.includes(normalizedQuery))
+        score += 20;
+    for (const term of terms) {
+        let matchedTerm = false;
+        for (const [field, value] of Object.entries(values)) {
+            if (value.includes(term)) {
+                fields.add(field);
+                matchedTerm = true;
+                score += field === 'statement' ? 5 : field === 'scope' ? 4 : 3;
+            }
+        }
+        if (matchedTerm)
+            matched.add(term);
+    }
+    if (values.scope === normalizedQuery)
+        score += 10;
+    return { fields: [...fields], matchedTerms: [...matched], score };
+}
+function limitedKnowledge(knowledge, maxChars) {
+    const statement = knowledge.statement.length <= maxChars ? knowledge.statement : `${knowledge.statement.slice(0, Math.max(0, maxChars - 1))}…`;
+    return { ...knowledge, statement, supportingEvidence: knowledge.supportingEvidence.map((item) => item.length <= maxChars ? item : `${item.slice(0, Math.max(0, maxChars - 1))}…`) };
+}
+export async function discoverKnowledge(startPath, query, options = {}) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    const cleanQuery = query.trim();
+    if (!cleanQuery)
+        throw new Error('knowledge discovery query must not be empty');
+    const file = await loadKnowledge(projectRoot);
+    const statuses = options.statuses ?? ['verified'];
+    const terms = queryTerms(cleanQuery);
+    const matches = file.items
+        .filter((item) => statuses.includes(item.status))
+        .filter((item) => !options.scope || normalized(item.scope) === normalized(options.scope))
+        .map((knowledge) => ({ knowledge, ...matchedFields(knowledge, terms) }))
+        .filter((item) => item.matchedTerms.length > 0)
+        .sort((left, right) => right.score - left.score || Number(right.knowledge.status === 'verified') - Number(left.knowledge.status === 'verified') || right.knowledge.confidence - left.knowledge.confidence || right.knowledge.updatedAt.localeCompare(left.knowledge.updatedAt) || left.knowledge.knowledgeId.localeCompare(right.knowledge.knowledgeId));
+    const duplicateMap = new Map();
+    for (const item of file.items) {
+        const key = `${normalized(item.kind)}|${normalized(item.scope)}|${normalized(item.statement)}`;
+        duplicateMap.set(key, [...(duplicateMap.get(key) ?? []), item.knowledgeId]);
+    }
+    const duplicateIds = [...duplicateMap.values()].filter((ids) => ids.length > 1);
+    const possibleConflicts = file.items.flatMap((left, index) => file.items.slice(index + 1).filter((right) => normalized(left.scope) === normalized(right.scope) && normalized(left.statement) !== normalized(right.statement) && queryTerms(left.statement).some((term) => normalized(right.statement).includes(term))).map((right) => ({ scope: left.scope, knowledgeIds: [left.knowledgeId, right.knowledgeId], statements: [left.statement, right.statement] })));
+    const limit = options.limit ?? 10;
+    const selected = matches.slice(0, limit);
+    const maxChars = options.maxChars ?? 4000;
+    const hits = selected.map((item) => ({ knowledge: limitedKnowledge(item.knowledge, maxChars), score: item.score, matchedTerms: item.matchedTerms, matchedFields: item.fields, why: item.fields.map((field) => `matched ${field}`) }));
+    return { query: cleanQuery, total: matches.length, truncated: matches.length > selected.length, hits, duplicateIds, possibleConflicts };
+}
 export async function verifyKnowledge(startPath, knowledgeId) {
     const projectRoot = await resolveProjectRoot(startPath);
     return withLock(`${locksDirectory(projectRoot)}/knowledge.lock`, async () => {
@@ -117,6 +241,49 @@ export async function listDeadends(startPath, includeUnverified = false) {
     const file = await loadDeadends(projectRoot);
     return includeUnverified ? file.items : file.items.filter((item) => item.status === 'verified');
 }
+function limitedDeadend(deadend, maxChars) {
+    const limit = (value) => value.length <= maxChars ? value : `${value.slice(0, Math.max(0, maxChars - 1))}…`;
+    return { ...deadend, attempt: limit(deadend.attempt), reason: limit(deadend.reason), observedEvidence: deadend.observedEvidence.map(limit) };
+}
+export async function discoverDeadends(startPath, query, options = {}) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    const cleanQuery = query.trim();
+    if (!cleanQuery)
+        throw new Error('deadend discovery query must not be empty');
+    const terms = normalized(cleanQuery).split(/\s+/).filter(Boolean);
+    const statuses = options.statuses ?? ['verified'];
+    const file = await loadDeadends(projectRoot);
+    const matches = file.items
+        .filter((item) => statuses.includes(item.status))
+        .filter((item) => !options.scope || normalized(item.scope) === normalized(options.scope))
+        .map((deadend) => {
+        const values = { attempt: normalized(deadend.attempt), reason: normalized(deadend.reason), scope: normalized(deadend.scope) };
+        const fields = new Set();
+        const matchedTerms = new Set();
+        let score = 0;
+        for (const term of terms) {
+            for (const [field, value] of Object.entries(values)) {
+                if (value.includes(term)) {
+                    fields.add(field);
+                    matchedTerms.add(term);
+                    score += field === 'attempt' ? 5 : field === 'reason' ? 4 : 3;
+                }
+            }
+        }
+        return { deadend, score, matchedTerms: [...matchedTerms], matchedFields: [...fields] };
+    })
+        .filter((item) => item.matchedTerms.length > 0)
+        .sort((left, right) => right.score - left.score || right.deadend.updatedAt.localeCompare(left.deadend.updatedAt) || left.deadend.deadendId.localeCompare(right.deadend.deadendId));
+    const limit = options.limit ?? 10;
+    const selected = matches.slice(0, limit);
+    const maxChars = options.maxChars ?? 4000;
+    return {
+        query: cleanQuery,
+        total: matches.length,
+        truncated: matches.length > selected.length,
+        hits: selected.map((item) => ({ ...item, deadend: limitedDeadend(item.deadend, maxChars) })),
+    };
+}
 export async function verifyDeadend(startPath, deadendId) {
     const projectRoot = await resolveProjectRoot(startPath);
     return withLock(`${locksDirectory(projectRoot)}/deadends.lock`, async () => {

package/dist/src/runtime/notes.js

@@ -0,0 +1,173 @@
+import crypto from 'node:crypto';
+import { access, readdir } from 'node:fs/promises';
+import { resolveProjectRoot } from '../project/project-resolver.js';
+import { filterPaths } from '../capture/context-filter.js';
+import { atomicWriteJson } from '../storage/atomic-write.js';
+import { isRecord, readJson } from '../storage/json-store.js';
+import { contextMetadataPath, contextsRoot, locksDirectory, notesPath, snapshotPath, snapshotsDirectory } from '../storage/layout.js';
+import { withLock } from '../storage/lock.js';
+function id() {
+    return `note-${Date.now().toString(36)}-${crypto.randomBytes(4).toString('hex')}`;
+}
+function isNotFound(error) {
+    return typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT';
+}
+function isNote(value) {
+    return isRecord(value)
+        && value.schemaVersion === 1
+        && typeof value.noteId === 'string'
+        && ['problem', 'action', 'observation', 'decision'].includes(value.kind)
+        && typeof value.message === 'string'
+        && value.message.trim().length > 0
+        && ['agent', 'human'].includes(value.actor)
+        && (typeof value.contextId === 'string' || value.contextId === null)
+        && (typeof value.snapshotId === 'string' || value.snapshotId === null)
+        && Array.isArray(value.relatedFiles) && value.relatedFiles.every((item) => typeof item === 'string')
+        && ['open', 'resolved'].includes(value.status)
+        && (typeof value.absorbedBySnapshotId === 'string' || value.absorbedBySnapshotId === null)
+        && typeof value.createdAt === 'string'
+        && typeof value.updatedAt === 'string';
+}
+function isNoteFile(value) {
+    return isRecord(value) && value.schemaVersion === 1 && Array.isArray(value.items) && value.items.every(isNote);
+}
+async function loadNotes(projectRoot) {
+    try {
+        return await readJson(notesPath(projectRoot), isNoteFile);
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return { schemaVersion: 1, items: [] };
+        throw error;
+    }
+}
+async function validateSource(projectRoot, contextId, snapshotId) {
+    if (!contextId && snapshotId)
+        throw new Error('source snapshot requires source context');
+    if (!contextId)
+        return;
+    await access(contextMetadataPath(projectRoot, contextId));
+    if (snapshotId)
+        await access(snapshotPath(projectRoot, contextId, snapshotId));
+}
+function limited(value, budget) {
+    return value.length <= budget ? value : value.slice(0, Math.max(0, budget - 1)) + '…';
+}
+export async function addNote(startPath, message, input = {}) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    const normalizedMessage = message.trim();
+    if (!normalizedMessage)
+        throw new Error('note message must not be empty');
+    await validateSource(projectRoot, input.contextId, input.snapshotId);
+    const relatedFiles = await filterPaths(projectRoot, (input.relatedFiles ?? []).map((item) => item.trim()).filter(Boolean));
+    return withLock(`${locksDirectory(projectRoot)}/notes.lock`, async () => {
+        const file = await loadNotes(projectRoot);
+        const now = new Date().toISOString();
+        const note = {
+            noteId: id(),
+            schemaVersion: 1,
+            kind: input.kind ?? 'observation',
+            message: normalizedMessage,
+            actor: input.actor ?? 'agent',
+            contextId: input.contextId ?? null,
+            snapshotId: input.snapshotId ?? null,
+            relatedFiles,
+            status: input.status ?? 'open',
+            absorbedBySnapshotId: null,
+            createdAt: now,
+            updatedAt: now,
+        };
+        await atomicWriteJson(notesPath(projectRoot), { schemaVersion: 1, items: [...file.items, note] });
+        return note;
+    });
+}
+export async function listNotes(startPath, query = {}) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    const file = await loadNotes(projectRoot);
+    const limit = query.limit ?? 50;
+    const maxChars = query.maxChars ?? 500;
+    return file.items
+        .filter((note) => !query.contextId || note.contextId === query.contextId)
+        .filter((note) => !query.openOnly || (note.status === 'open' && note.absorbedBySnapshotId === null))
+        .sort((left, right) => right.createdAt.localeCompare(left.createdAt))
+        .slice(0, limit)
+        .map((note) => ({ ...note, message: limited(note.message, maxChars) }));
+}
+function noteActivity(note) {
+    if (!note.contextId)
+        return null;
+    return {
+        type: 'note',
+        occurredAt: note.createdAt,
+        contextId: note.contextId,
+        snapshotId: note.snapshotId ?? undefined,
+        noteId: note.noteId,
+        kind: note.kind,
+        message: note.message,
+        actor: note.actor,
+        status: note.status,
+        absorbedBySnapshotId: note.absorbedBySnapshotId,
+    };
+}
+async function checkpointActivities(projectRoot, contextId) {
+    const items = [];
+    let contextIds;
+    try {
+        contextIds = await readdir(contextsRoot(projectRoot));
+    }
+    catch {
+        contextIds = [];
+    }
+    for (const id of contextIds) {
+        if (contextId && id !== contextId)
+            continue;
+        try {
+            const context = await readJson(contextMetadataPath(projectRoot, id), (value) => isRecord(value) && typeof value.id === 'string' && typeof value.title === 'string' && (typeof value.currentSnapshotId === 'string' || value.currentSnapshotId === null));
+            if (!context.currentSnapshotId)
+                continue;
+            const snapshots = await readdir(snapshotsDirectory(projectRoot, id));
+            for (const fileName of snapshots.filter((name) => name.endsWith('.json'))) {
+                const snapshot = await readJson(snapshotPath(projectRoot, id, fileName.slice(0, -5)), (value) => isRecord(value) && value.schemaVersion === 1 && typeof value.snapshotId === 'string' && typeof value.createdAt === 'string' && (value.mode === 'baseline' || value.mode === 'patch'));
+                items.push({ type: 'checkpoint', occurredAt: snapshot.createdAt, contextId: id, snapshotId: snapshot.snapshotId, title: context.title });
+            }
+        }
+        catch {
+            // Doctor reports malformed activity sources.
+        }
+    }
+    return items;
+}
+export async function listActivity(startPath, query = {}) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    const notes = await loadNotes(projectRoot);
+    const noteItems = notes.items.map(noteActivity).filter((item) => item !== null);
+    const checkpointItems = await checkpointActivities(projectRoot, query.contextId);
+    const maxChars = query.maxChars ?? 500;
+    const items = [...noteItems, ...checkpointItems]
+        .filter((item) => !query.contextId || item.contextId === query.contextId)
+        .filter((item) => !query.since || item.occurredAt >= query.since)
+        .filter((item) => !query.openOnly || (item.type === 'note' && item.status === 'open' && item.absorbedBySnapshotId === null))
+        .sort((left, right) => right.occurredAt.localeCompare(left.occurredAt))
+        .slice(0, query.limit ?? 50)
+        .map((item) => item.message ? { ...item, message: limited(item.message, maxChars) } : item);
+    return { projectRoot, items };
+}
+export async function absorbNotes(startPath, contextId, snapshotId) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    return withLock(`${locksDirectory(projectRoot)}/notes.lock`, async () => {
+        const file = await loadNotes(projectRoot);
+        let absorbed = 0;
+        const items = file.items.map((note) => {
+            if (note.contextId !== contextId || note.absorbedBySnapshotId !== null)
+                return note;
+            absorbed += 1;
+            return { ...note, absorbedBySnapshotId: snapshotId, updatedAt: new Date().toISOString() };
+        });
+        if (absorbed > 0)
+            await atomicWriteJson(notesPath(projectRoot), { schemaVersion: 1, items });
+        return absorbed;
+    });
+}
+export function isValidNote(value) {
+    return isNote(value);
+}

package/dist/src/runtime/runtime.js

@@ -8,6 +8,7 @@ import { withLock } from '../storage/lock.js';
 import { contextDirectory, contextMetadataPath, contextsRoot, indexPath, locksDirectory, snapshotPath, snapshotsDirectory, } from '../storage/layout.js';
 import { loadManifest } from './init.js';
 import { filterPaths } from '../capture/context-filter.js';
+import { absorbNotes } from './notes.js';
 const emptyContext = () => ({
     progressSummary: '',
     lastError: null,
@@ -46,6 +47,29 @@ function limitedList(values, budget) {
 function applyPatch(base, patch) {
     return { ...base, ...patch };
 }
+function isContextPatch(value) {
+    if (!isRecord(value))
+        return false;
+    const fields = ['progressSummary', 'lastError', 'completed', 'pendingTasks', 'decisions', 'risks', 'relatedFiles'];
+    if (Object.keys(value).some((key) => !fields.includes(key)))
+        return false;
+    return fields.every((field) => {
+        if (!(field in value))
+            return true;
+        const fieldValue = value[field];
+        if (field === 'lastError')
+            return typeof fieldValue === 'string' || fieldValue === null;
+        if (field === 'progressSummary')
+            return typeof fieldValue === 'string';
+        return isStringArray(fieldValue);
+    });
+}
+function normalizeText(value) {
+    return value.trim();
+}
+function normalizeList(values) {
+    return values.map(normalizeText).filter(Boolean);
+}
 function diffContext(previous, current) {
     const patch = {};
     if (previous.progressSummary !== current.progressSummary)
@@ -65,16 +89,17 @@ function diffContext(previous, current) {
     return patch;
 }
 async function contextFromInput(projectRoot, input, previous) {
-    const relatedFiles = await filterPaths(projectRoot, input.relatedFiles ?? previous?.relatedFiles ?? []);
-    return {
-        progressSummary: input.progressSummary ?? previous?.progressSummary ?? '',
-        lastError: input.lastError === undefined ? previous?.lastError ?? null : input.lastError,
-        completed: input.completed ?? previous?.completed ?? [],
-        pendingTasks: input.pendingTasks ?? previous?.pendingTasks ?? [],
-        decisions: input.decisions ?? previous?.decisions ?? [],
-        risks: input.risks ?? previous?.risks ?? [],
-        relatedFiles,
-    };
+    const progressSummary = input.progressSummary === undefined ? previous?.progressSummary ?? '' : normalizeText(input.progressSummary);
+    const lastError = input.lastError === undefined
+        ? previous?.lastError ?? null
+        : normalizeText(input.lastError ?? '') || null;
+    const completed = input.completed === undefined ? previous?.completed ?? [] : normalizeList(input.completed);
+    const pendingTasks = input.pendingTasks === undefined ? previous?.pendingTasks ?? [] : normalizeList(input.pendingTasks);
+    const decisions = input.decisions === undefined ? previous?.decisions ?? [] : normalizeList(input.decisions);
+    const risks = input.risks === undefined ? previous?.risks ?? [] : normalizeList(input.risks);
+    const relatedFilesInput = input.relatedFiles === undefined ? previous?.relatedFiles ?? [] : normalizeList(input.relatedFiles);
+    const relatedFiles = await filterPaths(projectRoot, relatedFilesInput);
+    return { progressSummary, lastError, completed, pendingTasks, decisions, risks, relatedFiles };
 }
 function isStructuredContext(value) {
     return isRecord(value)
@@ -126,7 +151,7 @@ async function loadSnapshot(projectRoot, contextId, snapshotId) {
     }
     return snapshot;
 }
-async function rebuildSnapshot(projectRoot, contextId, snapshotId, seen = new Set()) {
+export async function rebuildSnapshot(projectRoot, contextId, snapshotId, seen = new Set()) {
     if (seen.has(snapshotId))
         throw new Error(`snapshot cycle detected at ${snapshotId}`);
     seen.add(snapshotId);
@@ -139,7 +164,7 @@ async function rebuildSnapshot(projectRoot, contextId, snapshotId, seen = new Se
         content = snapshot.content;
     }
     else {
-        if (!snapshot.parentSnapshotId || !snapshot.patch || !isRecord(snapshot.patch))
+        if (!snapshot.parentSnapshotId || !snapshot.patch || !isContextPatch(snapshot.patch))
             throw new Error(`incomplete patch snapshot ${snapshotId}`);
         const parentSnapshot = await loadSnapshot(projectRoot, contextId, snapshot.parentSnapshotId);
         if (parentSnapshot.baseSnapshotId !== snapshot.baseSnapshotId)
@@ -151,7 +176,7 @@ async function rebuildSnapshot(projectRoot, contextId, snapshotId, seen = new Se
     }
     return content;
 }
-export async function rebuildIndex(projectRoot) {
+export async function rebuildIndex(projectRoot, persist = true) {
     const contexts = [];
     let entries = [];
     try {
@@ -178,7 +203,8 @@ export async function rebuildIndex(projectRoot) {
         }
     }
     const index = { schemaVersion: 1, rebuiltAt: new Date().toISOString(), contexts };
-    await atomicWriteJson(indexPath(projectRoot), index);
+    if (persist)
+        await atomicWriteJson(indexPath(projectRoot), index);
     return index;
 }
 async function updateIndex(projectRoot, entry) {
@@ -279,6 +305,8 @@ export async function checkpoint(startPath, input, options = {}) {
             currentSnapshotId: snapshotId,
             updatedAt: now,
         });
+        if (input.absorbNotes)
+            await absorbNotes(projectRoot, contextId, snapshotId);
         return { status: 'saved', context: updatedContext, snapshot };
     });
 }

package/dist/src/storage/layout.js

@@ -35,3 +35,6 @@ export function knowledgePath(projectRoot) {
 export function deadendsPath(projectRoot) {
     return path.join(contextRoot(projectRoot), 'deadends.json');
 }
+export function notesPath(projectRoot) {
+    return path.join(contextRoot(projectRoot), 'notes.json');
+}

package/dist/src/version.js

@@ -0,0 +1 @@
+export const VERSION = '0.2.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fluffy-context",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "面向 AI 编程会话的本地上下文运行时 CLI",
   "type": "module",
   "keywords": [
@@ -18,6 +18,11 @@
   "bin": {
     "ctx": "dist/src/cli/main.js"
   },
+  "exports": {
+    ".": "./dist/src/agent/index.js",
+    "./agent": "./dist/src/agent/index.js",
+    "./version": "./dist/src/version.js"
+  },
   "files": [
     "dist/src"
   ],