@vinsonw2/asset-compound 0.0.0-stage → 0.1.1

package/dist/types/types.d.ts

@@ -0,0 +1,88 @@
+export type SourceType = "requirement" | "design" | "ai-artifact" | "git";
+export type ChangeKind = "新增" | "增量" | "未变";
+export interface SourceSet {
+    type: SourceType;
+    include?: string[];
+    maxCommits?: number;
+}
+export interface RunConfig {
+    outputRoot: "docs/可读化";
+    baseBranch?: string;
+    sourceSets: SourceSet[];
+    exclude?: string[];
+}
+export interface DimensionFinding {
+    level: "ready" | "partial" | "missing" | "conflict" | "high" | "medium" | "low";
+    evidence: string[];
+    gaps: string[];
+    recommendations: string[];
+}
+export interface AssetRecord {
+    assetId: string;
+    sourceType: SourceType;
+    sourceRef: string;
+    sourceRevision: string;
+    contentHash: string;
+    title: string;
+    summary: string;
+    facts: string[];
+    decisions: string[];
+    actions: string[];
+    relations: string[];
+    analysis: {
+        completeness: DimensionFinding;
+        executability: DimensionFinding;
+        consistency: DimensionFinding;
+        reuseValue: DimensionFinding;
+    };
+    writebackKind: ChangeKind;
+}
+export interface SourceState {
+    contentHash: string;
+    sourceRevision: string;
+    assetIds: string[];
+    status: "active" | "stale";
+}
+export interface AssetState {
+    canonicalContentHash: string;
+    outputPath: string;
+    lastGeneratedHash: string;
+}
+export interface ReadState {
+    schemaVersion: 1;
+    selfHash: string;
+    baseBranch: string;
+    baseCommit: string;
+    lastReadCommit: string;
+    sources: Record<string, SourceState>;
+    assets: Record<string, AssetState>;
+    managedFiles: Record<string, string>;
+}
+export interface ScanRecord {
+    sourceType: SourceType;
+    sourceRef: string;
+    sourceRevision: string;
+    contentHash: string;
+    content: string;
+}
+export interface Conflict {
+    assetId: string;
+    path: string;
+    reason: string;
+    expectedHash?: string;
+    actualHash?: string;
+}
+export interface PipelineResult {
+    runId: string;
+    counts: {
+        new: number;
+        updated: number;
+        unchanged: number;
+        conflicts: number;
+    };
+    assets: AssetRecord[];
+    conflicts: Conflict[];
+    changedFiles: string[];
+    noOp: boolean;
+    secondRunZeroDiff?: boolean;
+}

package/package.json

@@ -1,6 +1,83 @@
 {
   "name": "@vinsonw2/asset-compound",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Editor-neutral CLI and protocol for incremental, traceable documentation assets",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/types/index.d.ts",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "asset-compound": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "schemas",
+    "templates",
+    "prompts",
+    "protocol",
+    "skill",
+    "artifacts"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./schemas/*": "./schemas/*",
+    "./templates/*": "./templates/*",
+    "./prompts/*": "./prompts/*",
+    "./protocol/*": "./protocol/*",
+    "./cursor-skill": "./skill/asset-compounding/SKILL.md",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsup && tsc -p tsconfig.build.json",
+    "dev": "tsx src/cli.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "smoke": "node scripts/smoke.mjs",
+    "smoke:packed": "node scripts/packed-smoke.mjs",
+    "check": "npm run typecheck && npm run test && npm run build",
+    "prepack": "npm run check"
+  },
+  "keywords": [
+    "ai-editor",
+    "documentation",
+    "incremental",
+    "knowledge-management",
+    "cli"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vinsonw/ai.git"
+  },
+  "homepage": "https://github.com/vinsonw/ai#readme",
+  "bugs": {
+    "url": "https://github.com/vinsonw/ai/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "MIT",
+  "packageManager": "pnpm@10.33.4",
+  "dependencies": {
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
+    "commander": "^15.1.0",
+    "fast-glob": "^3.3.3",
+    "write-file-atomic": "^8.0.0",
+    "yaml": "^2.9.1"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.6",
+    "@types/write-file-atomic": "^4.0.3",
+    "tsup": "^9.0.0",
+    "tsx": "^4.23.15",
+    "typescript": "^7.0.2",
+    "vitest": "^5.1.0"
+  }
+}

package/prompts/asset-analysis.zh-CN.md

@@ -0,0 +1,59 @@
+# 资产复利四维分析提示协议
+
+你正在分析真实项目材料。输入文件是 `asset-compound prepare` 生成的 JSON 数组，输出必须仍是 JSON 数组，并通过随包提供的 `schemas/analysis-output.schema.json`。
+
+## 不可修改字段
+
+每条记录的以下字段是确定性来源契约，禁止修改：
+
+- `assetId`
+- `sourceType`
+- `sourceRef`
+- `sourceRevision`
+- `contentHash`
+- `writebackKind`
+
+禁止增加、删除或复制数组元素。每个来源必须恰好对应一条资产。
+
+## 可以增强的字段
+
+- `title`
+- `summary`
+- `facts`
+- `decisions`
+- `actions`
+- `relations`
+- `analysis`
+
+## 四维分析
+
+对每条资产分别填写：
+
+1. `analysis.completeness`：完整性。材料是否覆盖目标、范围、约束、边界、异常和验收条件。
+2. `analysis.executability`：可执行性。是否有明确行动、负责人、前置条件、完成定义和验证办法。
+3. `analysis.consistency`：一致性。与其他需求、设计、AI 产物和 Git 决策是否相容。
+4. `analysis.reuseValue`：复用价值。是否可沉淀为检查表、模板、规则、ADR 或后续任务输入。
+
+每个维度必须包含：
+
+- `level`
+- `evidence`
+- `gaps`
+- `recommendations`
+
+`level` 的稳定枚举是：
+
+- `ready`
+- `partial`
+- `missing`
+- `conflict`
+- `high`
+- `medium`
+- `low`
+
+## 安全要求
+
+- 不得写入密钥、令牌、邮箱或未经授权的私有标识。
+- 不得编造来源中不存在的事实。
+- 不确定内容必须放入 `gaps` 或 `recommendations`，不能伪装为已确认结论。
+- 最终只输出 JSON，不添加 Markdown 代码围栏或解释文字。

package/protocol/README.zh-CN.md

@@ -0,0 +1,49 @@
+# 编辑器无关资产复利协议
+
+本协议不假设存在统一的 AI 编辑器 Skill 标准。任何能够读取和编辑文件的 AI 工具，都可以按下列文件契约参与。
+
+## 角色分工
+
+- `asset-compound`：确定性扫描、hash、增量 state、schema 校验、安全回写。
+- AI 编辑器：在禁止修改来源契约字段的前提下，补充语义资产和四维分析。
+- 人工验收者：确认真实来源范围、结论质量、冲突、分支和证据。
+
+## 文件流
+
+1. 用户在目标仓库之外保存 `run.yaml`。
+2. `asset-compound prepare ... > prepared.json` 生成 AI 输入。
+3. AI 按 `asset-analysis.zh-CN.md` 将结果写为 `enriched.json`。
+4. `asset-compound validate --input enriched.json` 做独立 schema 校验。
+5. `asset-compound finalize ... --assets enriched.json` 再核对当前扫描的 provenance，并只写 `docs/可读化/**`。
+6. `asset-compound verify --repo ... --config ...` 证明无变化二次运行。
+
+## 初始化目录
+
+`npx @vinsonw2/asset-compound init --output <目录>` 会生成：
+
+```text
+<目录>/
+├── README.md
+├── run.yaml
+├── prompts/
+│   └── asset-analysis.zh-CN.md
+├── protocol/
+│   └── README.zh-CN.md
+└── schemas/
+    ├── analysis-input.schema.json
+    └── analysis-output.schema.json
+```
+
+该目录应位于目标仓库之外。若必须放入目标仓库，应先提交为受控配置；否则 CLI 的工作树边界检查会拒绝写入。
+
+## 稳定契约
+
+命令名、JSON 字段和枚举保持英文。中文提示只负责解释，不得改名。完整字段以 `schemas/*.json` 为准。
+
+## 验收边界
+
+- 至少两种不同、真实、非空的来源类型。
+- 示例和 fixture 不能作为真实验收数据。
+- AI 输出必须经过 `validate`。
+- CLI 输出仅允许位于 `docs/可读化/**`。
+- 二次运行必须输出 `secondRunZeroDiff: true`。

package/schemas/analysis-input.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://asset-compound.dev/schemas/analysis-input.schema.json",
+  "title": "Four-dimension analysis input",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "sourceType",
+    "sourceRef",
+    "sourceRevision",
+    "contentHash",
+    "content"
+  ],
+  "properties": {
+    "sourceType": {
+      "enum": ["requirement", "design", "ai-artifact", "git"]
+    },
+    "sourceRef": {
+      "type": "string",
+      "minLength": 1
+    },
+    "sourceRevision": {
+      "type": "string",
+      "minLength": 1
+    },
+    "contentHash": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "content": {
+      "type": "string"
+    }
+  }
+}

package/schemas/analysis-output.schema.json

@@ -0,0 +1,117 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://asset-compound.dev/schemas/analysis-output.schema.json",
+  "title": "Structured asset with four-dimension analysis",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "assetId",
+    "sourceType",
+    "sourceRef",
+    "sourceRevision",
+    "contentHash",
+    "title",
+    "summary",
+    "facts",
+    "decisions",
+    "actions",
+    "relations",
+    "analysis",
+    "writebackKind"
+  ],
+  "properties": {
+    "assetId": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "sourceType": {
+      "enum": ["requirement", "design", "ai-artifact", "git"]
+    },
+    "sourceRef": {
+      "type": "string",
+      "minLength": 1
+    },
+    "sourceRevision": {
+      "type": "string",
+      "minLength": 1
+    },
+    "contentHash": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1
+    },
+    "summary": {
+      "type": "string"
+    },
+    "facts": {
+      "type": "array",
+      "items": {"type": "string"}
+    },
+    "decisions": {
+      "type": "array",
+      "items": {"type": "string"}
+    },
+    "actions": {
+      "type": "array",
+      "items": {"type": "string"}
+    },
+    "relations": {
+      "type": "array",
+      "items": {"type": "string"}
+    },
+    "analysis": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "completeness",
+        "executability",
+        "consistency",
+        "reuseValue"
+      ],
+      "properties": {
+        "completeness": {"$ref": "#/$defs/dimension"},
+        "executability": {"$ref": "#/$defs/dimension"},
+        "consistency": {"$ref": "#/$defs/dimension"},
+        "reuseValue": {"$ref": "#/$defs/dimension"}
+      }
+    },
+    "writebackKind": {
+      "enum": ["新增", "增量", "未变"]
+    }
+  },
+  "$defs": {
+    "dimension": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["level", "evidence", "gaps", "recommendations"],
+      "properties": {
+        "level": {
+          "enum": [
+            "ready",
+            "partial",
+            "missing",
+            "conflict",
+            "high",
+            "medium",
+            "low"
+          ]
+        },
+        "evidence": {
+          "type": "array",
+          "items": {"type": "string"}
+        },
+        "gaps": {
+          "type": "array",
+          "items": {"type": "string"}
+        },
+        "recommendations": {
+          "type": "array",
+          "items": {"type": "string"}
+        }
+      }
+    }
+  }
+}

package/schemas/read-state.schema.json

@@ -0,0 +1,90 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://asset-compound.dev/schemas/read-state.schema.json",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "selfHash",
+    "baseBranch",
+    "baseCommit",
+    "lastReadCommit",
+    "sources",
+    "assets",
+    "managedFiles"
+  ],
+  "properties": {
+    "schemaVersion": {"const": 1},
+    "selfHash": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "baseBranch": {"type": "string"},
+    "baseCommit": {"type": "string"},
+    "lastReadCommit": {"type": "string"},
+    "sources": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "contentHash",
+          "sourceRevision",
+          "assetIds",
+          "status"
+        ],
+        "properties": {
+          "contentHash": {
+            "type": "string",
+            "pattern": "^sha256:[a-f0-9]{64}$"
+          },
+          "sourceRevision": {"type": "string"},
+          "assetIds": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "pattern": "^sha256:[a-f0-9]{64}$"
+            }
+          },
+          "status": {"enum": ["active", "stale"]}
+        }
+      }
+    },
+    "assets": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "canonicalContentHash",
+          "outputPath",
+          "lastGeneratedHash"
+        ],
+        "properties": {
+          "canonicalContentHash": {
+            "type": "string",
+            "pattern": "^sha256:[a-f0-9]{64}$"
+          },
+          "outputPath": {
+            "type": "string",
+            "pattern": "^(?!.*(?:^|/)\\.\\.(?:/|$))docs/可读化/.+$"
+          },
+          "lastGeneratedHash": {
+            "type": "string",
+            "pattern": "^sha256:[a-f0-9]{64}$"
+          }
+        }
+      }
+    },
+    "managedFiles": {
+      "type": "object",
+      "propertyNames": {
+        "pattern": "^(?!.*(?:^|/)\\.\\.(?:/|$))docs/可读化/.+$"
+      },
+      "additionalProperties": {
+        "type": "string",
+        "pattern": "^sha256:[a-f0-9]{64}$"
+      }
+    }
+  }
+}

package/skill/asset-compounding/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: asset-compounding
+description: 读取至少两类真实来源，提取可追溯资产，执行四维分析，并仅向 docs/可读化 增量回写。
+---
+
+# 资产复利
+
+这是 `@vinsonw2/asset-compound` npm 包的**可选 Cursor 适配器**。核心 CLI、schema、templates、prompts 和通用 protocol 不依赖 Cursor。任意 AI 编辑器应使用 `npx @vinsonw2/asset-compound init` 生成的编辑器无关文件协议；本项目不假装存在跨编辑器统一 Skill 标准。
+
+当 Cursor 中的真实项目需要把需求、设计、AI 产物和 Git 历史沉淀为可复用、可增量、可审计的文档资产时，使用此适配器。
+
+## 前置条件
+
+1. 确认目标仓库、基线分支和允许读取的来源 glob。
+2. 至少提供两种不同类型、真实、非空且有业务意义的来源；fixture 和空 API 不能作为验收数据。
+3. CLI 工具包必须放在目标仓库之外。
+4. 任何写入前，必须从当前基线创建独立分支。
+
+## 执行流程
+
+1. 运行 `npx @vinsonw2/asset-compound plan --repo <仓库> --config <run.yaml>`。
+2. 运行 `npx @vinsonw2/asset-compound scan`，检查每个来源路径和 revision。
+3. 运行 `npx @vinsonw2/asset-compound prepare ... > prepared.json`。需要业务判断时补充严格 JSON；不得修改 ID、hash 和来源追踪字段。
+4. 确保每条资产分别包含完整性、可执行性、一致性、复用价值四项结论，每项均有证据、缺口和建议。
+5. 运行 `npx @vinsonw2/asset-compound validate --input enriched.json`。预览写入集合；只有全部路径都位于 `docs/可读化/**` 时，才运行 `npx @vinsonw2/asset-compound render ... --assets enriched.json`。
+6. 运行 `npx @vinsonw2/asset-compound verify --repo <仓库> --config <run.yaml>`，保存其中的 `secondRunZeroDiff` JSON 作为 V6 证据。
+7. 运行 `npx @vinsonw2/asset-compound finalize`，保存验收报告。
+8. 在独立分支提交；禁止直接推送基线分支。
+9. 使用完全相同的输入执行第二次运行，要求业务产物零 diff，且 `new=0 updated=0`。
+10. 如需证明受控增量，只能使用一份已批准的真实来源变更，并证明仅对应资产发生增量。
+
+## 安全规则
+
+- 禁止修改应用源码、包清单、原始需求/设计/AI 材料，以及 `docs/可读化/**` 之外的路径。
+- 当前文件 hash 与 state 不一致时，禁止静默覆盖；必须保留原文件并生成冲突报告。
+- schema 校验失败或检测到越界写入后，禁止推进 state。
+- 模型输出属于不可信输入，只有通过随包提供的 JSON Schema 后才能渲染。
+- 增量身份必须使用来源内容 hash，禁止使用模型摘要。
+- Markdown 和截图必须移除密钥、令牌、邮箱等隐私标识。
+
+## 稳定契约中英映射
+
+代码标识符、命令名和 JSON/schema 字段保持英文，以保障自动化兼容：
+
+| 稳定字段 | 中文含义 |
+|---|---|
+| `sourceType` / `sourceRef` / `sourceRevision` | 来源类型 / 来源定位 / 来源版本 |
+| `contentHash` / `assetId` | 内容指纹 / 稳定资产 ID |
+| `analysis.completeness` | 完整性 |
+| `analysis.executability` | 可执行性 |
+| `analysis.consistency` | 一致性 |
+| `analysis.reuseValue` | 复用价值 |
+| `writebackKind` | 回写标记 |
+| `new` / `updated` / `unchanged` / `conflicts` | 新增 / 增量 / 未变 / 冲突 |
+| `secondRunZeroDiff` | 第二次运行业务产物零差异 |
+
+## 必备证据
+
+- 至少两类真实非空来源的来源清单。
+- 结构化资产与完整的四维分析。
+- 独立分支、提交记录和路径边界验证。
+- state 前后版本、稳定 ID、hash 和 Git revision。
+- 冲突报告；无冲突时也必须明确记录“0 个冲突”。
+- 首次运行结果与无变化二次运行结果。
+- 覆盖 R1–R6 和 V1–V8 的验收报告。

package/templates/acceptance-report.md

@@ -0,0 +1,23 @@
+# 资产复利验收报告
+
+- 运行 ID：`{{run_id}}`
+- 分支：`{{branch}}`
+- 基线提交 / 当前提交：`{{base_sha}}` / `{{head_sha}}`
+- 来源：{{source_type_summary}}
+- 统计：新增 {{new_count}}，增量 {{updated_count}}，未变 {{unchanged_count}}，冲突 {{conflict_count}}
+
+## R1–R6
+
+{{requirements_matrix}}
+
+## V1–V8
+
+{{verification_matrix}}
+
+## 四维结论摘要
+
+{{four_dimension_summary}}
+
+## 冲突与证据
+
+{{conflict_and_evidence_links}}

package/templates/conflict-report.md

@@ -0,0 +1,8 @@
+# 冲突报告
+
+- 运行 ID：`{{run_id}}`
+- 冲突数：{{conflict_count}}
+
+{{conflicts}}
+
+> 冲突必须透明记录；禁止静默覆盖人工编辑或来源歧义。