fluffy-context 0.1.0

package/README.md

@@ -0,0 +1,242 @@
+# Context Runtime
+
+Context Runtime 是一个面向 AI 编程会话的本地上下文运行时 CLI。它把一次任务的进度、决策、待办、风险、知识和已验证死路保存为可恢复的结构化状态，帮助 Agent 在新会话中快速完成交接，而不是重新阅读大量项目内容。
+
+它更接近“Context 的 Git”，而不是代码备份工具：Git 仍然负责代码和真实文件变更，Context Runtime 负责 AI 工作状态的版本化保存与恢复。
+
+## 适用场景
+
+- 下班前保存当前任务状态，第二天继续工作。
+- 保存完成项、待办、阻塞、决策和风险。
+- 将可复用业务知识独立记录，并在确认后纳入知识库。
+- 记录已经验证不可行的方案，避免新会话重复探索。
+- 通过摘要预算恢复上下文，减少不必要的 Token 消耗。
+
+## 环境要求
+
+- Node.js `>=20.19.0`
+- Git 可选。项目位于 Git 仓库内时，CLI 会记录当前分支和 commit 信息。
+
+## 安装
+
+发布后可以使用 npm 全局安装：
+
+```bash
+npm install --global fluffy-context
+```
+
+也可以在项目目录中直接运行：
+
+```bash
+npx fluffy-context --help
+```
+
+## 快速开始
+
+在项目根目录初始化 Context Runtime：
+
+```bash
+ctx init
+```
+
+这会创建以下本地文件：
+
+```text
+.context/
+├── manifest.json
+├── index.json
+├── contexts/
+├── locks/
+├── knowledge.json    # 首次使用 learn 后创建
+└── deadends.json     # 首次使用 deadend 后创建
+.contextignored
+```
+
+保存一次工作状态：
+
+```bash
+ctx checkpoint \
+  --title "订单状态机重构" \
+  --progress "完成状态流转梳理，正在补充异常路径测试" \
+  --completed "梳理状态转移,确认幂等策略" \
+  --pending "补充异常路径测试,运行集成测试" \
+  --decisions "订单状态由服务端状态机统一维护" \
+  --risks "第三方回调可能重复到达" \
+  --files "src/order/state-machine.ts,src/order/state-machine.test.ts"
+```
+
+第二天恢复：
+
+```bash
+ctx resume
+```
+
+`resume` 默认返回轻量摘要，同时保留完整详情供按需使用。可以限制摘要字符数：
+
+```bash
+ctx resume --max-chars 2000
+```
+
+## 常用命令
+
+### `ctx init`
+
+初始化项目的 Context Runtime 存储布局。重复执行是幂等的，不会覆盖已有 Context 或项目忽略规则。
+
+```bash
+ctx init
+ctx init path/to/project
+ctx init --path path/to/project
+```
+
+### `ctx checkpoint`
+
+保存结构化工作状态。第一次保存创建 baseline，后续有变化时保存 patch；内容没有变化时返回 `no_change`。
+
+```bash
+ctx checkpoint \
+  --context <context-id> \
+  --title "修复支付回调" \
+  --progress "已定位签名校验失败原因" \
+  --last-error "测试环境缺少回调凭据" \
+  --completed "复现问题,确认签名字段" \
+  --pending "补充回归测试" \
+  --decisions "保留原始请求体用于验签" \
+  --risks "旧版客户端字段格式不同" \
+  --files "src/payment/webhook.ts"
+```
+
+列表参数使用逗号分隔。`--context` 省略时会创建新的 Context。默认情况下，实际保存之间至少间隔 10 秒；短时间内有变化的保存会返回 `rate_limited`，没有变化则返回 `no_change`。
+
+### `ctx resume`
+
+恢复一个 active 或 stable Context。默认优先选择当前分支上最近更新的 Context，并返回 Git 分支/commit 是否发生漂移。
+
+```bash
+ctx resume
+ctx resume --context <context-id>
+ctx resume --path path/to/project --max-chars 4000
+```
+
+### `ctx status`
+
+查看项目是否已初始化以及当前 Context 索引：
+
+```bash
+ctx status
+```
+
+### `ctx doctor`
+
+检查 Manifest、存储目录、索引、Context 元数据、当前 Snapshot 和索引重建一致性：
+
+```bash
+ctx doctor
+```
+
+### `ctx learn`
+
+记录一条待确认的项目知识。Knowledge 默认是 `candidate`，不会进入普通的已验证知识列表。
+
+```bash
+ctx learn "订单取消后不能再次进入支付中状态" \
+  --scope project \
+  --context <context-id> \
+  --snapshot <snapshot-id> \
+  --evidence "src/order/state-machine.ts,订单服务接口约束"
+```
+
+查看和确认知识：
+
+```bash
+ctx knowledge
+ctx knowledge --all
+ctx knowledge verify <knowledge-id>
+```
+
+不提供 `--context` 时，知识仍可以记录为项目级候选知识；如果提供来源，则对应 Context 和 Snapshot 必须存在。
+
+### `ctx deadend`
+
+记录一条已尝试但不可行的路径。Deadend 默认是 `candidate`，不会默认注入恢复摘要。
+
+```bash
+ctx deadend \
+  --attempt "使用共享可变单例保存订单状态" \
+  --reason "并发测试出现跨用例状态泄漏" \
+  --scope project \
+  --context <context-id> \
+  --evidence "test/order-state.test.ts"
+```
+
+查看和确认死路：
+
+```bash
+ctx deadends
+ctx deadends --all
+ctx deadend verify <deadend-id>
+```
+
+## `.contextignored`
+
+`ctx init` 会在项目根目录创建 `.contextignored`。它用于配置不应作为上下文关联文件保存的路径，语法接近 `.gitignore`：
+
+```gitignore
+# 私有目录
+private/
+
+# 本地生成文件
+*.generated.ts
+
+# 不纳入上下文的临时记录
+notes/draft-*
+```
+
+内置保护规则始终优先，包括 `.context/`、`.git/`、依赖目录、构建产物、环境变量文件、密钥和常见凭据文件。项目规则不能通过否定规则覆盖这些保护。
+
+## 存储与安全边界
+
+- Snapshot 按 baseline/patch 保存，不会每次复制整个项目文件树。
+- `index.json` 是可重建索引，不是唯一业务数据来源。
+- Context、Knowledge、Deadend 使用独立文件保存。
+- 写入使用临时文件替换，并通过项目级锁避免并发覆盖。
+- 默认只恢复摘要字段；完整结构化内容位于 `details` 中按需读取。
+- CLI 不会读取或保存被内置保护规则排除的文件内容。
+
+## 命令输出
+
+CLI 默认向标准输出写入格式化 JSON，适合被脚本、Agent 或 IDE 集成：
+
+```bash
+ctx --help
+ctx --version
+```
+
+错误信息写入标准错误，并以非零退出码结束。
+
+## 开发
+
+安装依赖并运行测试：
+
+```bash
+npm install
+npm test
+```
+
+只构建 TypeScript：
+
+```bash
+npm run build
+```
+
+本项目核心运行时只依赖 Node.js 内置模块，当前没有运行时第三方依赖。
+
+## 当前范围
+
+当前版本聚焦本地单项目的可靠闭环：
+
+```text
+init → checkpoint → resume
+```
+
+并提供基础的 Knowledge、Deadend、忽略规则、诊断、Snapshot 增量保存、摘要预算和保存限流能力。远程同步、多人协作、复杂语义检索、自动模型总结和 Context merge 不属于当前版本的已实现能力。

package/dist/src/capture/context-filter.js

@@ -0,0 +1,86 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { ignoredPath } from '../storage/layout.js';
+const builtinPatterns = [
+    '.context/**',
+    '.git/**',
+    'node_modules/**',
+    'dist/**',
+    'build/**',
+    'coverage/**',
+    'tmp/**',
+    '.cache/**',
+    '.env',
+    '.env.*',
+    '*.pem',
+    '*.key',
+    '*.p12',
+    '*.pfx',
+    'credentials*',
+    '*credential*',
+    'secret*',
+    '*token*',
+];
+function globToRegExp(pattern) {
+    let source = '';
+    for (let index = 0; index < pattern.length; index += 1) {
+        const character = pattern[index];
+        if (character === '*') {
+            if (pattern[index + 1] === '*') {
+                source += '.*';
+                index += 1;
+            }
+            else {
+                source += '[^/]*';
+            }
+        }
+        else if (character === '?') {
+            source += '[^/]';
+        }
+        else {
+            source += /[\\^$+?.()|[\]{}]/.test(character) ? `\\${character}` : character;
+        }
+    }
+    return new RegExp(`^${source}$`);
+}
+function matches(pattern, relativePath) {
+    const directoryPattern = pattern.endsWith('/');
+    const normalized = pattern.replace(/^\//, '').replace(/\/$/, '');
+    const expression = globToRegExp(directoryPattern ? `${normalized}/**` : normalized);
+    return expression.test(relativePath) || (!pattern.startsWith('/') && expression.test(relativePath.split('/').slice(-1)[0]));
+}
+export async function readProjectRules(projectRoot) {
+    try {
+        const content = await readFile(ignoredPath(projectRoot), 'utf8');
+        return content
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter((line) => line && !line.startsWith('#'))
+            .map((line) => ({ negated: line.startsWith('!'), pattern: line.replace(/^!/, '') }));
+    }
+    catch {
+        return [];
+    }
+}
+export async function filterPaths(projectRoot, paths) {
+    const projectRules = await readProjectRules(projectRoot);
+    return paths
+        .map((filePath) => filePath.replaceAll('\\', '/').replace(/^\.\//, ''))
+        .filter((relativePath) => {
+        if (path.posix.isAbsolute(relativePath) || path.win32.isAbsolute(relativePath))
+            return false;
+        const normalized = path.posix.normalize(relativePath);
+        if (normalized === '..' || normalized.startsWith('../'))
+            return false;
+        if (builtinPatterns.some((pattern) => matches(pattern, normalized)))
+            return false;
+        let included = true;
+        for (const rule of projectRules) {
+            if (matches(rule.pattern, normalized)) {
+                included = rule.negated;
+            }
+        }
+        return included;
+    })
+        .map((filePath) => path.posix.normalize(filePath));
+}

package/dist/src/cli/main.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+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';
+function option(args, name) {
+    const index = args.indexOf(name);
+    if (index < 0)
+        return undefined;
+    const value = args[index + 1];
+    if (!value || 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;
+}
+function positionals(args, options) {
+    const values = [];
+    for (let index = 0; index < args.length; index += 1) {
+        if (args[index].startsWith('--') || args[index] === '-m') {
+            if (options.includes(args[index]))
+                index += 1;
+            continue;
+        }
+        values.push(args[index]);
+    }
+    return values;
+}
+function validateOptions(args, allowed) {
+    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')
+            index += 1;
+    }
+}
+function numericOption(args, name, defaultValue) {
+    const value = option(args, name);
+    if (!value)
+        return defaultValue;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 0)
+        throw new Error(`${name} must be a non-negative integer`);
+    return parsed;
+}
+function usage() {
+    return 'usage: ctx init|checkpoint|resume|status|doctor|learn|knowledge|deadend|deadends [options]';
+}
+function print(value) {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+async function run(args) {
+    if (args.includes('--version')) {
+        print('0.1.0');
+        return;
+    }
+    if (args.length === 0 || args.includes('--help')) {
+        process.stdout.write(`${usage()}\n`);
+        return;
+    }
+    const command = args[0];
+    const target = option(args, '--path');
+    switch (command) {
+        case 'init':
+            print(await initProject(target ?? args[1]));
+            return;
+        case 'checkpoint': {
+            const input = {
+                contextId: option(args, '--context'),
+                title: option(args, '--title'),
+                progressSummary: option(args, '--progress'),
+                lastError: option(args, '--last-error') ?? null,
+                completed: listOption(args, '--completed'),
+                pendingTasks: listOption(args, '--pending'),
+                decisions: listOption(args, '--decisions'),
+                risks: listOption(args, '--risks'),
+                relatedFiles: listOption(args, '--files'),
+            };
+            print(await checkpoint(target, input));
+            return;
+        }
+        case 'resume':
+            validateOptions(args.slice(1), ['--path', '--context', '--max-chars']);
+            print(await resume(target, option(args, '--context'), numericOption(args, '--max-chars', 4000)));
+            return;
+        case 'status':
+            print(await status(target));
+            return;
+        case 'doctor':
+            print(await doctor(target));
+            return;
+        case 'learn': {
+            const statement = positionals(args.slice(1), ['--path', '--scope', '--context', '--snapshot', '--evidence']);
+            const input = {
+                scope: option(args, '--scope'),
+                sourceContextId: option(args, '--context'),
+                sourceSnapshotId: option(args, '--snapshot'),
+                evidence: listOption(args, '--evidence'),
+            };
+            print(await learnKnowledge(target, statement.join(' '), input));
+            return;
+        }
+        case 'knowledge':
+            if (args[1] === 'verify')
+                print(await verifyKnowledge(target, args[2]));
+            else
+                print(await listKnowledge(target, args.includes('--all')));
+            return;
+        case 'deadend':
+            if (args[1] === 'verify')
+                print(await verifyDeadend(target, args[2]));
+            else {
+                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));
+            }
+            return;
+        case 'deadends':
+            print(await listDeadends(target, args.includes('--all')));
+            return;
+        default:
+            throw new Error(usage());
+    }
+}
+run(process.argv.slice(2)).catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+});

package/dist/src/git/git-adapter.js

@@ -0,0 +1,23 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+async function git(args, cwd) {
+    try {
+        const result = await execFileAsync('git', args, { cwd, windowsHide: true });
+        return result.stdout.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function readGitState(projectRoot) {
+    const root = await git(['rev-parse', '--show-toplevel'], projectRoot);
+    if (!root) {
+        return { root: null, branch: null, commit: null };
+    }
+    return {
+        root,
+        branch: await git(['branch', '--show-current'], projectRoot),
+        commit: await git(['rev-parse', 'HEAD'], projectRoot),
+    };
+}

package/dist/src/project/project-resolver.js

@@ -0,0 +1,39 @@
+import { access, stat } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import path from 'node:path';
+const execFileAsync = promisify(execFile);
+async function gitRoot(directory) {
+    try {
+        const result = await execFileAsync('git', ['rev-parse', '--show-toplevel'], {
+            cwd: directory,
+            windowsHide: true,
+        });
+        return result.stdout.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function resolveProjectRoot(startPath = process.cwd()) {
+    const initial = path.resolve(startPath);
+    const directory = (await stat(initial)).isDirectory() ? initial : path.dirname(initial);
+    const root = await gitRoot(directory);
+    if (root) {
+        return path.resolve(root);
+    }
+    let current = directory;
+    while (true) {
+        try {
+            await access(path.join(current, '.context'));
+            return current;
+        }
+        catch {
+            const parent = path.dirname(current);
+            if (parent === current) {
+                return directory;
+            }
+            current = parent;
+        }
+    }
+}

package/dist/src/runtime/diagnostics.js

@@ -0,0 +1,70 @@
+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';
+export async function status(startPath) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    try {
+        const manifest = await readJson(manifestPath(projectRoot));
+        const index = await readJson(indexPath(projectRoot));
+        return {
+            initialized: true,
+            projectRoot,
+            layoutVersion: manifest.layoutVersion,
+            contextCount: index.contexts.length,
+            contexts: index.contexts,
+        };
+    }
+    catch {
+        return { initialized: false, projectRoot };
+    }
+}
+export async function doctor(startPath) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    const checks = [];
+    let healthy = true;
+    const check = async (name, operation) => {
+        try {
+            await operation();
+            checks.push(`${name}: ok`);
+        }
+        catch (error) {
+            healthy = false;
+            checks.push(`${name}: ${error instanceof Error ? error.message : 'failed'}`);
+        }
+    };
+    await check('manifest', async () => {
+        const manifest = await readJson(manifestPath(projectRoot));
+        if (manifest.schemaVersion !== 1 || manifest.layoutVersion !== 'compact-json-v1' || manifest.projectRoot !== projectRoot) {
+            throw new Error('invalid manifest');
+        }
+    });
+    await check('context directory', () => access(contextRoot(projectRoot)));
+    await check('index', async () => {
+        const index = await readJson(indexPath(projectRoot));
+        if (index.schemaVersion !== 1 || !Array.isArray(index.contexts))
+            throw new Error('invalid index');
+    });
+    await check('contexts', async () => {
+        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)
+                throw new Error(`invalid context ${contextId}`);
+            if (context.currentSnapshotId)
+                await access(snapshotPath(projectRoot, contextId, context.currentSnapshotId));
+        }
+    });
+    await check('index rebuild', async () => {
+        const stored = await readJson(indexPath(projectRoot));
+        const rebuilt = await rebuildIndex(projectRoot);
+        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)
+            throw new Error('duplicate index context id');
+        if (rebuiltIds.size !== storedIds.size || [...rebuiltIds].some((id) => !storedIds.has(id)))
+            throw new Error('index rebuild mismatch');
+    });
+    return { healthy, projectRoot, checks };
+}

package/dist/src/runtime/init.js

@@ -0,0 +1,47 @@
+import { mkdir, access, writeFile } from 'node:fs/promises';
+import crypto from 'node:crypto';
+import { resolveProjectRoot } from '../project/project-resolver.js';
+import { atomicWriteJson } from '../storage/atomic-write.js';
+import { readJson } from '../storage/json-store.js';
+import { ignoredPath, indexPath, locksDirectory, manifestPath, contextsRoot, } from '../storage/layout.js';
+const ignoredTemplate = `# Context Runtime project rules\n# Add paths that must never enter context collection.\n\n# Build output\ndist/\nbuild/\ncoverage/\n\n# Local secrets\n.env\n.env.*\n`;
+export async function initProject(startPath) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    const manifestFile = manifestPath(projectRoot);
+    const requiredPaths = [manifestFile, indexPath(projectRoot), contextsRoot(projectRoot), locksDirectory(projectRoot)];
+    let present = 0;
+    for (const requiredPath of requiredPaths) {
+        try {
+            await access(requiredPath);
+            present += 1;
+        }
+        catch {
+            // Missing path is handled below.
+        }
+    }
+    if (present === requiredPaths.length)
+        return { projectRoot, alreadyInitialized: true };
+    if (present > 0)
+        throw new Error('context layout is incomplete; run ctx doctor before repairing it');
+    await mkdir(contextsRoot(projectRoot), { recursive: true });
+    await mkdir(locksDirectory(projectRoot), { recursive: true });
+    const manifest = {
+        schemaVersion: 1,
+        layoutVersion: 'compact-json-v1',
+        projectId: crypto.createHash('sha256').update(projectRoot).digest('hex').slice(0, 16),
+        projectRoot,
+        initializedAt: new Date().toISOString(),
+    };
+    await atomicWriteJson(manifestFile, manifest);
+    await atomicWriteJson(indexPath(projectRoot), { schemaVersion: 1, rebuiltAt: new Date().toISOString(), contexts: [] });
+    try {
+        await access(ignoredPath(projectRoot));
+    }
+    catch {
+        await writeFile(ignoredPath(projectRoot), ignoredTemplate, 'utf8');
+    }
+    return { projectRoot, alreadyInitialized: false };
+}
+export async function loadManifest(projectRoot) {
+    return readJson(manifestPath(projectRoot));
+}

package/dist/src/runtime/knowledge.js

@@ -0,0 +1,132 @@
+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';
+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 isKnowledgeFile(value) {
+    return isRecord(value) && value.schemaVersion === 1 && Array.isArray(value.items);
+}
+function isDeadendFile(value) {
+    return isRecord(value) && value.schemaVersion === 1 && Array.isArray(value.items);
+}
+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));
+}
+async function loadKnowledge(projectRoot) {
+    try {
+        return await readJson(knowledgePath(projectRoot), isKnowledgeFile);
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return { schemaVersion: 1, items: [] };
+        throw error;
+    }
+}
+async function loadDeadends(projectRoot) {
+    try {
+        return await readJson(deadendsPath(projectRoot), isDeadendFile);
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return { schemaVersion: 1, items: [] };
+        throw error;
+    }
+}
+export async function learnKnowledge(startPath, statement, scopeOrInput = 'project') {
+    const projectRoot = await resolveProjectRoot(startPath);
+    const input = typeof scopeOrInput === 'string' ? { scope: scopeOrInput } : scopeOrInput;
+    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',
+            confidence: 0.5,
+            status: 'candidate',
+            sourceContextIds: input.sourceContextId ? [input.sourceContextId] : [],
+            sourceSnapshotIds: input.sourceSnapshotId ? [input.sourceSnapshotId] : [],
+            supportingEvidence: input.evidence ?? [],
+            createdAt: now,
+            updatedAt: now,
+        };
+        await atomicWriteJson(knowledgePath(projectRoot), { schemaVersion: 1, items: [...file.items, item] });
+        return item;
+    });
+}
+export async function listKnowledge(startPath, includeUnverified = false) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    const file = await loadKnowledge(projectRoot);
+    return includeUnverified ? file.items : file.items.filter((item) => item.status === 'verified');
+}
+export async function verifyKnowledge(startPath, knowledgeId) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    return withLock(`${locksDirectory(projectRoot)}/knowledge.lock`, async () => {
+        const file = await loadKnowledge(projectRoot);
+        const item = file.items.find((candidate) => candidate.knowledgeId === knowledgeId);
+        if (!item)
+            throw new Error(`knowledge not found: ${knowledgeId}`);
+        item.status = 'verified';
+        item.confidence = Math.max(item.confidence, 0.8);
+        item.updatedAt = new Date().toISOString();
+        await atomicWriteJson(knowledgePath(projectRoot), file);
+        return item;
+    });
+}
+export async function recordDeadend(startPath, attempt, reason, scopeOrInput = 'project') {
+    const projectRoot = await resolveProjectRoot(startPath);
+    const input = typeof scopeOrInput === 'string' ? { scope: scopeOrInput } : scopeOrInput;
+    await validateSource(projectRoot, input.sourceContextId, input.sourceSnapshotId);
+    return withLock(`${locksDirectory(projectRoot)}/deadends.lock`, async () => {
+        const file = await loadDeadends(projectRoot);
+        const now = new Date().toISOString();
+        const item = {
+            deadendId: id('dead'),
+            attempt,
+            reason,
+            observedEvidence: input.evidence ?? [],
+            scope: input.scope ?? 'project',
+            status: 'candidate',
+            sourceContextId: input.sourceContextId ?? null,
+            sourceSnapshotId: input.sourceSnapshotId ?? null,
+            createdAt: now,
+            updatedAt: now,
+        };
+        await atomicWriteJson(deadendsPath(projectRoot), { schemaVersion: 1, items: [...file.items, item] });
+        return item;
+    });
+}
+export async function listDeadends(startPath, includeUnverified = false) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    const file = await loadDeadends(projectRoot);
+    return includeUnverified ? file.items : file.items.filter((item) => item.status === 'verified');
+}
+export async function verifyDeadend(startPath, deadendId) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    return withLock(`${locksDirectory(projectRoot)}/deadends.lock`, async () => {
+        const file = await loadDeadends(projectRoot);
+        const item = file.items.find((candidate) => candidate.deadendId === deadendId);
+        if (!item)
+            throw new Error(`deadend not found: ${deadendId}`);
+        item.status = 'verified';
+        item.updatedAt = new Date().toISOString();
+        await atomicWriteJson(deadendsPath(projectRoot), file);
+        return item;
+    });
+}

package/dist/src/runtime/runtime.js

@@ -0,0 +1,317 @@
+import crypto from 'node:crypto';
+import { mkdir } from 'node:fs/promises';
+import { readGitState } from '../git/git-adapter.js';
+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 { contextDirectory, contextMetadataPath, contextsRoot, indexPath, locksDirectory, snapshotPath, snapshotsDirectory, } from '../storage/layout.js';
+import { loadManifest } from './init.js';
+import { filterPaths } from '../capture/context-filter.js';
+const emptyContext = () => ({
+    progressSummary: '',
+    lastError: null,
+    completed: [],
+    pendingTasks: [],
+    decisions: [],
+    risks: [],
+    relatedFiles: [],
+});
+function stableJson(value) {
+    return JSON.stringify(value);
+}
+function hash(value) {
+    return crypto.createHash('sha256').update(stableJson(value)).digest('hex');
+}
+function createId(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 limited(value, budget) {
+    return value.length <= budget ? value : value.slice(0, Math.max(0, budget - 1)) + '…';
+}
+function limitedList(values, budget) {
+    const result = [];
+    for (const value of values) {
+        if (budget.remaining <= 0)
+            break;
+        const item = limited(value, budget.remaining);
+        result.push(item);
+        budget.remaining -= item.length;
+    }
+    return result;
+}
+function applyPatch(base, patch) {
+    return { ...base, ...patch };
+}
+function diffContext(previous, current) {
+    const patch = {};
+    if (previous.progressSummary !== current.progressSummary)
+        patch.progressSummary = current.progressSummary;
+    if (previous.lastError !== current.lastError)
+        patch.lastError = current.lastError;
+    if (stableJson(previous.completed) !== stableJson(current.completed))
+        patch.completed = current.completed;
+    if (stableJson(previous.pendingTasks) !== stableJson(current.pendingTasks))
+        patch.pendingTasks = current.pendingTasks;
+    if (stableJson(previous.decisions) !== stableJson(current.decisions))
+        patch.decisions = current.decisions;
+    if (stableJson(previous.risks) !== stableJson(current.risks))
+        patch.risks = current.risks;
+    if (stableJson(previous.relatedFiles) !== stableJson(current.relatedFiles))
+        patch.relatedFiles = current.relatedFiles;
+    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,
+    };
+}
+function isStructuredContext(value) {
+    return isRecord(value)
+        && typeof value.progressSummary === 'string'
+        && (typeof value.lastError === 'string' || value.lastError === null)
+        && ['completed', 'pendingTasks', 'decisions', 'risks', 'relatedFiles'].every((key) => isStringArray(value[key]));
+}
+function isSnapshot(value) {
+    return isRecord(value)
+        && value.schemaVersion === 1
+        && typeof value.snapshotId === 'string'
+        && typeof value.contextId === 'string'
+        && (typeof value.parentSnapshotId === 'string' || value.parentSnapshotId === null)
+        && typeof value.baseSnapshotId === 'string'
+        && (value.mode === 'baseline' || value.mode === 'patch')
+        && typeof value.createdAt === 'string'
+        && (typeof value.branch === 'string' || value.branch === null)
+        && (typeof value.commit === 'string' || value.commit === null)
+        && typeof value.contentHash === 'string'
+        && typeof value.rebuildHash === 'string';
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+function isContextMetadata(value, contextId) {
+    return isRecord(value)
+        && value.schemaVersion === 1
+        && value.id === contextId
+        && typeof value.title === 'string'
+        && typeof value.projectRoot === 'string'
+        && (typeof value.branch === 'string' || value.branch === null)
+        && (typeof value.commit === 'string' || value.commit === null)
+        && typeof value.createdAt === 'string'
+        && typeof value.updatedAt === 'string'
+        && (typeof value.lastUsedAt === 'string' || value.lastUsedAt === null)
+        && typeof value.usageCount === 'number'
+        && ['draft', 'active', 'stable', 'archived', 'deleted'].includes(value.status)
+        && (typeof value.currentSnapshotId === 'string' || value.currentSnapshotId === null)
+        && isStringArray(value.tags)
+        && isStringArray(value.dependencies);
+}
+async function loadContext(projectRoot, contextId) {
+    return readJson(contextMetadataPath(projectRoot, contextId), (value) => isContextMetadata(value, contextId));
+}
+async function loadSnapshot(projectRoot, contextId, snapshotId) {
+    const snapshot = await readJson(snapshotPath(projectRoot, contextId, snapshotId), isSnapshot);
+    if (snapshot.contextId !== contextId || snapshot.snapshotId !== snapshotId) {
+        throw new Error(`invalid snapshot ${snapshotId}`);
+    }
+    return snapshot;
+}
+async function rebuildSnapshot(projectRoot, contextId, snapshotId, seen = new Set()) {
+    if (seen.has(snapshotId))
+        throw new Error(`snapshot cycle detected at ${snapshotId}`);
+    seen.add(snapshotId);
+    const snapshot = await loadSnapshot(projectRoot, contextId, snapshotId);
+    let content;
+    if (snapshot.mode === 'baseline') {
+        if (!snapshot.content || !isStructuredContext(snapshot.content) || snapshot.parentSnapshotId !== null || snapshot.baseSnapshotId !== snapshot.snapshotId) {
+            throw new Error(`invalid baseline snapshot ${snapshotId}`);
+        }
+        content = snapshot.content;
+    }
+    else {
+        if (!snapshot.parentSnapshotId || !snapshot.patch || !isRecord(snapshot.patch))
+            throw new Error(`incomplete patch snapshot ${snapshotId}`);
+        const parentSnapshot = await loadSnapshot(projectRoot, contextId, snapshot.parentSnapshotId);
+        if (parentSnapshot.baseSnapshotId !== snapshot.baseSnapshotId)
+            throw new Error(`base_snapshot_mismatch for ${snapshotId}`);
+        content = applyPatch(await rebuildSnapshot(projectRoot, contextId, snapshot.parentSnapshotId, seen), snapshot.patch);
+    }
+    if (hash(content) !== snapshot.contentHash || hash(content) !== snapshot.rebuildHash) {
+        throw new Error(`snapshot hash mismatch for ${snapshotId}`);
+    }
+    return content;
+}
+export async function rebuildIndex(projectRoot) {
+    const contexts = [];
+    let entries = [];
+    try {
+        entries = await (await import('node:fs/promises')).readdir(contextsRoot(projectRoot));
+    }
+    catch {
+        entries = [];
+    }
+    for (const contextId of entries) {
+        try {
+            const context = await loadContext(projectRoot, contextId);
+            contexts.push({
+                contextId: context.id,
+                title: context.title,
+                status: context.status,
+                branch: context.branch,
+                commit: context.commit,
+                currentSnapshotId: context.currentSnapshotId,
+                updatedAt: context.updatedAt,
+            });
+        }
+        catch {
+            // Doctor reports malformed context metadata; it is not indexed.
+        }
+    }
+    const index = { schemaVersion: 1, rebuiltAt: new Date().toISOString(), contexts };
+    await atomicWriteJson(indexPath(projectRoot), index);
+    return index;
+}
+async function updateIndex(projectRoot, entry) {
+    const index = await rebuildIndex(projectRoot);
+    const contexts = index.contexts.filter((item) => item.contextId !== entry.contextId);
+    contexts.push(entry);
+    await atomicWriteJson(indexPath(projectRoot), { schemaVersion: 1, rebuiltAt: new Date().toISOString(), contexts });
+}
+export async function checkpoint(startPath, input, options = {}) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    await loadManifest(projectRoot);
+    const git = await readGitState(projectRoot);
+    const contextId = input.contextId ?? createId('ctx');
+    const lockPath = `${locksDirectory(projectRoot)}/checkpoint.lock`;
+    return withLock(lockPath, async () => {
+        let context;
+        let previous = emptyContext();
+        let previousSnapshot = null;
+        try {
+            context = await loadContext(projectRoot, contextId);
+            if (context.currentSnapshotId) {
+                previousSnapshot = await loadSnapshot(projectRoot, contextId, context.currentSnapshotId);
+                previous = await rebuildSnapshot(projectRoot, contextId, context.currentSnapshotId);
+            }
+        }
+        catch (error) {
+            if (input.contextId || !isNotFound(error))
+                throw error;
+            context = {
+                id: contextId,
+                schemaVersion: 1,
+                title: input.title ?? 'Untitled context',
+                projectRoot,
+                branch: git.branch,
+                commit: git.commit,
+                createdAt: new Date().toISOString(),
+                updatedAt: new Date().toISOString(),
+                lastUsedAt: null,
+                usageCount: 0,
+                status: 'draft',
+                currentSnapshotId: null,
+                tags: [],
+                dependencies: [],
+            };
+        }
+        const content = await contextFromInput(projectRoot, input, previous);
+        const patch = diffContext(previous, content);
+        if (previousSnapshot && Object.keys(patch).length === 0)
+            return { status: 'no_change', context, snapshot: previousSnapshot };
+        const minSaveIntervalMs = options.minSaveIntervalMs ?? 10_000;
+        const lastSavedAt = Date.parse(context.updatedAt);
+        if (previousSnapshot && Number.isFinite(lastSavedAt) && Date.now() - lastSavedAt < minSaveIntervalMs) {
+            return {
+                status: 'rate_limited',
+                context,
+                snapshot: previousSnapshot,
+                retryAt: new Date(lastSavedAt + minSaveIntervalMs).toISOString(),
+            };
+        }
+        const now = new Date().toISOString();
+        const snapshotId = createId('snap');
+        const mode = previousSnapshot ? 'patch' : 'baseline';
+        const snapshot = {
+            snapshotId,
+            schemaVersion: 1,
+            contextId,
+            parentSnapshotId: previousSnapshot?.snapshotId ?? null,
+            baseSnapshotId: previousSnapshot?.baseSnapshotId ?? snapshotId,
+            mode,
+            createdAt: now,
+            branch: git.branch,
+            commit: git.commit,
+            contentHash: hash(content),
+            rebuildHash: hash(content),
+            ...(mode === 'baseline' ? { content } : { patch }),
+        };
+        await mkdir(contextDirectory(projectRoot, contextId), { recursive: true });
+        await mkdir(snapshotsDirectory(projectRoot, contextId), { recursive: true });
+        await atomicWriteJson(snapshotPath(projectRoot, contextId, snapshotId), snapshot);
+        const updatedContext = {
+            ...context,
+            title: input.title ?? context.title,
+            branch: git.branch,
+            commit: git.commit,
+            updatedAt: now,
+            lastUsedAt: now,
+            usageCount: context.usageCount + 1,
+            status: 'active',
+            currentSnapshotId: snapshotId,
+        };
+        await atomicWriteJson(contextMetadataPath(projectRoot, contextId), updatedContext);
+        await updateIndex(projectRoot, {
+            contextId,
+            title: updatedContext.title,
+            status: updatedContext.status,
+            branch: updatedContext.branch,
+            commit: updatedContext.commit,
+            currentSnapshotId: snapshotId,
+            updatedAt: now,
+        });
+        return { status: 'saved', context: updatedContext, snapshot };
+    });
+}
+export async function resume(startPath, contextId, maxChars = 4000) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    await loadManifest(projectRoot);
+    const git = await readGitState(projectRoot);
+    const index = await rebuildIndex(projectRoot);
+    const candidates = index.contexts
+        .filter((entry) => !contextId || entry.contextId === contextId)
+        .filter((entry) => ['active', 'stable'].includes(entry.status))
+        .sort((left, right) => Number(right.status === 'active') - Number(left.status === 'active') || Number(right.branch === git.branch) - Number(left.branch === git.branch) || right.updatedAt.localeCompare(left.updatedAt));
+    const candidate = candidates[0];
+    if (!candidate)
+        throw new Error('no active context found');
+    const context = await loadContext(projectRoot, candidate.contextId);
+    if (!context.currentSnapshotId)
+        throw new Error('context has no snapshot');
+    const snapshot = await loadSnapshot(projectRoot, candidate.contextId, context.currentSnapshotId);
+    const content = await rebuildSnapshot(projectRoot, candidate.contextId, snapshot.snapshotId);
+    const drift = context.branch !== git.branch || context.commit !== git.commit;
+    context.lastUsedAt = new Date().toISOString();
+    await atomicWriteJson(contextMetadataPath(projectRoot, context.id), context);
+    const budget = { remaining: Math.max(0, maxChars) };
+    const resumeSummary = {
+        progressSummary: limited(content.progressSummary, budget.remaining),
+        lastError: content.lastError === null ? null : limited(content.lastError, budget.remaining),
+        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: drift,
+    };
+    return { context, snapshot, resumeSummary, details: content };
+}

package/dist/src/runtime/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/storage/atomic-write.js

@@ -0,0 +1,13 @@
+import { mkdir, rename, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+export async function atomicWriteJson(filePath, value) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    const temporaryPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        await writeFile(temporaryPath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+        await rename(temporaryPath, filePath);
+    }
+    finally {
+        await rm(temporaryPath, { force: true });
+    }
+}

package/dist/src/storage/json-store.js

@@ -0,0 +1,26 @@
+import { readFile } from 'node:fs/promises';
+export class JsonStoreError extends Error {
+    filePath;
+    constructor(filePath, message) {
+        super(`${message}: ${filePath}`);
+        this.filePath = filePath;
+        this.name = 'JsonStoreError';
+    }
+}
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export async function readJson(filePath, validate) {
+    let value;
+    try {
+        value = JSON.parse(await readFile(filePath, 'utf8'));
+    }
+    catch (error) {
+        if (error instanceof SyntaxError)
+            throw new JsonStoreError(filePath, 'invalid JSON');
+        throw error;
+    }
+    if (validate && !validate(value))
+        throw new JsonStoreError(filePath, 'invalid data schema');
+    return value;
+}

package/dist/src/storage/layout.js

@@ -0,0 +1,37 @@
+import path from 'node:path';
+export function contextRoot(projectRoot) {
+    return path.join(projectRoot, '.context');
+}
+export function manifestPath(projectRoot) {
+    return path.join(contextRoot(projectRoot), 'manifest.json');
+}
+export function indexPath(projectRoot) {
+    return path.join(contextRoot(projectRoot), 'index.json');
+}
+export function ignoredPath(projectRoot) {
+    return path.join(projectRoot, '.contextignored');
+}
+export function contextsRoot(projectRoot) {
+    return path.join(contextRoot(projectRoot), 'contexts');
+}
+export function contextDirectory(projectRoot, contextId) {
+    return path.join(contextsRoot(projectRoot), contextId);
+}
+export function contextMetadataPath(projectRoot, contextId) {
+    return path.join(contextDirectory(projectRoot, contextId), 'context.json');
+}
+export function snapshotsDirectory(projectRoot, contextId) {
+    return path.join(contextDirectory(projectRoot, contextId), 'snaps');
+}
+export function snapshotPath(projectRoot, contextId, snapshotId) {
+    return path.join(snapshotsDirectory(projectRoot, contextId), `${snapshotId}.json`);
+}
+export function locksDirectory(projectRoot) {
+    return path.join(contextRoot(projectRoot), 'locks');
+}
+export function knowledgePath(projectRoot) {
+    return path.join(contextRoot(projectRoot), 'knowledge.json');
+}
+export function deadendsPath(projectRoot) {
+    return path.join(contextRoot(projectRoot), 'deadends.json');
+}

package/dist/src/storage/lock.js

@@ -0,0 +1,42 @@
+import { mkdir, open, readFile, rm } from 'node:fs/promises';
+import path from 'node:path';
+const staleLockMs = 60_000;
+async function isStale(lockPath) {
+    try {
+        const record = JSON.parse(await readFile(lockPath, 'utf8'));
+        const createdAt = Date.parse(record.createdAt ?? '');
+        return !Number.isFinite(createdAt) || Date.now() - createdAt > staleLockMs;
+    }
+    catch {
+        return true;
+    }
+}
+export async function withLock(lockPath, operation) {
+    await mkdir(path.dirname(lockPath), { recursive: true });
+    let handle;
+    try {
+        handle = await open(lockPath, 'wx');
+        await handle.writeFile(JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }));
+    }
+    catch {
+        if (await isStale(lockPath)) {
+            await rm(lockPath, { force: true });
+            handle = await open(lockPath, 'wx');
+            await handle.writeFile(JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }));
+        }
+        else {
+            throw new Error('context is busy; try again later');
+        }
+    }
+    try {
+        return await operation();
+    }
+    finally {
+        try {
+            await handle.close();
+        }
+        finally {
+            await rm(lockPath, { force: true });
+        }
+    }
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "fluffy-context",
+  "version": "0.1.0",
+  "description": "面向 AI 编程会话的本地上下文运行时 CLI",
+  "type": "module",
+  "keywords": [
+    "context-runtime",
+    "ai-agent",
+    "coding-agent",
+    "developer-tools",
+    "cli",
+    "context-management",
+    "session-resume",
+    "knowledge-base",
+    "deadend-tracking",
+    "snapshot"
+  ],
+  "bin": {
+    "ctx": "dist/src/cli/main.js"
+  },
+  "files": [
+    "dist/src"
+  ],
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test dist/test/*.test.js",
+    "ctx": "npm run build && node dist/src/cli/main.js"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.2"
+  }
+}