@zhaiye/codebase-ontology 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zhaiye
+
+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

@@ -0,0 +1,106 @@
+# Codebase Ontology Skill
+
+一个给 AI agent 使用的 skill，用于阅读代码库，并在目标 codebase 中生成业务 Ontology 五要素 YAML 文档。
+
+生成结果会写入目标 codebase 的 `.ontology/` 目录，并按五要素拆分：
+
+```text
+.ontology/
+  README.md
+  index.yaml
+  object-types/object-types.yaml
+  properties/properties.yaml
+  link-types/link-types.yaml
+  action-types/action-types.yaml
+  functions/functions.yaml
+```
+
+## 安装
+
+使用 npm 全局安装：
+
+```bash
+npm install -g @zhaiye/codebase-ontology
+```
+
+安装到 Codex 全局 skills：
+
+```bash
+codebase-ontology install --agent codex
+```
+
+安装到 Claude Code 全局 skills：
+
+```bash
+codebase-ontology install --agent claude
+```
+
+同时安装到 Codex 和 Claude Code：
+
+```bash
+codebase-ontology install --agent all
+```
+
+安装到当前项目：
+
+```bash
+codebase-ontology install --agent codex --scope project
+codebase-ontology install --agent claude --scope project
+```
+
+项目级安装路径分别是：
+
+```text
+Codex:      .codex/skills/codebase-ontology/
+Claude:     .claude/skills/codebase-ontology/
+```
+
+## 使用
+
+在目标代码库中，让 agent 使用该 skill：
+
+```text
+使用 $codebase-ontology 为当前代码库生成 .ontology 五要素 YAML 文档。
+```
+
+也可以直接描述任务：
+
+```text
+请分析这个 codebase，生成业务 ontology，并把五要素分别写到 .ontology 目录下。
+```
+
+## CLI
+
+查看将安装到哪里：
+
+```bash
+codebase-ontology doctor
+```
+
+预览安装但不写文件：
+
+```bash
+codebase-ontology install --agent all --dry-run
+```
+
+指定安装目录：
+
+```bash
+codebase-ontology install --target-dir ~/.codex/skills
+```
+
+卸载：
+
+```bash
+codebase-ontology uninstall --agent codex --yes
+```
+
+## 仓库结构
+
+```text
+SKILL.md
+references/ontology-output-structure.md
+agents/openai.yaml
+bin/codebase-ontology.js
+package.json
+```

package/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: codebase-ontology
+description: 生成代码库 Ontology 五要素文档。用于分析一个 codebase，并在该 codebase 根目录创建或更新 .ontology 目录，分别生成 Object Types、Properties、Link Types、Action Types、Functions 五类 YAML 文件；当用户要求 ontology 抽取、codebase ontology、业务实体建模、ontology.yaml 生成或按五要素整理代码库业务语义时使用。
+---
+
+# Codebase Ontology
+
+## 核心目标
+
+使用本 skill 阅读目标 codebase，并在该 codebase 根目录生成 `.ontology/` 目录。输出必须按五要素拆分为五个子目录和五个 YAML 文件，而不是写成一个大文档。
+
+强制目标结构：
+
+```text
+<codebase-root>/
+  .ontology/
+    README.md
+    index.yaml
+    object-types/object-types.yaml
+    properties/properties.yaml
+    link-types/link-types.yaml
+    action-types/action-types.yaml
+    functions/functions.yaml
+```
+
+不要把本 skill 的说明文件复制进目标 codebase。只生成目标 codebase 的 ontology 产物。
+
+## 建模原则
+
+- 建模真实业务世界，不机械复制数据库表、API schema、类图或目录结构。
+- 使用代码、测试、数据库 migration、API 路由、文档作为证据。
+- 没有证据不要臆造；不确定内容写入 `openQuestions`。
+- 五要素为：`Object Type`、`Property`、`Link Type`、`Action Type`、`Function`。
+- `Interface`、`Shared Property`、`Value Type` 只是扩展能力，可在相关 YAML 中作为辅助结构出现，不创建额外强制目录。
+- 每个重要 item 都要有 `sourceEvidence` 和 `confidence`。
+- 生成的 YAML 内容语言必须为中文；schema key、ID、代码路径、symbol、原始枚举值和外部系统名称可保持原文。
+
+## 输出语言要求
+
+生成到目标 codebase `.ontology/` 下的所有 YAML 文件，内容语言必须以中文为主。
+
+必须使用中文的字段：
+
+- `displayName`
+- `description`
+- `notes`
+- `question`
+- `suggestedResolution`
+- `qualityChecks.*.notes`
+- `guide.definition`
+- `guide` 下所有解释性文字
+- `.ontology/README.md` 中的人类可读内容
+- object、property、link、action、function 的业务语义说明
+
+可以保留原文的字段：
+
+- YAML schema key，如 `metadata`、`items`、`sourceEvidence`
+- 稳定机器 ID，如 `order`、`customerPlacesOrder`、`calculateOrderTotal`
+- 代码路径，如 `src/domain/order/Order.ts`
+- 代码 symbol，如 `OrderService.cancelOrder`
+- API path，如 `POST /orders/{orderId}/cancel`
+- 数据库表名、列名、外键名
+- 源代码中的枚举值和状态值，如 `draft`、`placed`、`cancelled`
+- 外部系统或第三方产品名称
+
+如果原始 codebase 使用英文领域词，`id` 可以保持英文 lowerCamelCase，但 `displayName` 和 `description` 必须翻译成中文。原始英文名称写入 `aliases` 或 `sourceEvidence`，不要丢失。
+
+## 工作流程
+
+1. 定位 codebase 根目录，确认要写入 `<codebase-root>/.ontology/`。
+2. 阅读 README、产品文档、API schema、路由、数据库 migration、ORM model、domain/service 层、测试。
+3. 总结业务域、用户角色、核心流程，写入 `.ontology/index.yaml` 和 `.ontology/README.md`。
+4. 抽取 Object Types：业务实体或业务事件。
+5. 抽取 Properties：对象的业务特征。
+6. 抽取 Link Types：对象之间的业务关系。
+7. 抽取 Action Types：用户、系统、任务或 agent 可执行的业务变更。
+8. 抽取 Functions：可复用业务逻辑，如计算、校验、权限、聚合、排序、推荐、风控。
+9. 为每个要素写证据，记录不确定问题。
+10. 运行质量检查，更新每个 YAML 的 `qualityChecks`。
+11. 检查所有生成 YAML 的人类可读内容是否为中文。
+
+## 文件写入规则
+
+必须创建或更新：
+
+- `.ontology/index.yaml`：索引、元数据、统计摘要、跨文件引用。
+- `.ontology/README.md`：人类可读摘要，简短说明核心对象、关系、动作、函数和未决问题。
+- `.ontology/object-types/object-types.yaml`：只放 Object Type 结果。
+- `.ontology/properties/properties.yaml`：只放 Property 结果，可包含 `valueTypes`、`sharedProperties`。
+- `.ontology/link-types/link-types.yaml`：只放 Link Type 结果。
+- `.ontology/action-types/action-types.yaml`：只放 Action Type 结果。
+- `.ontology/functions/functions.yaml`：只放 Function 结果。
+
+每个五要素 YAML 文件必须包含：
+
+```yaml
+metadata: {}
+guide: {}
+items: []
+sourceEvidence: []
+openQuestions: []
+qualityChecks: {}
+```
+
+详细模板和示例见 `references/ontology-output-structure.md`。当需要写入实际 YAML 文件时，必须先读取该参考文件。
+
+## 五要素抽取准则
+
+### Object Type
+
+创建条件：
+
+- 代表业务人员会自然讨论的实体或事件。
+- 有稳定身份，如 ID、编号、唯一键、事件 ID。
+- 有生命周期、状态、权限、审计或业务规则。
+- 会被多个功能读取、修改、关联或展示。
+
+不要创建：
+
+- Controller、Handler、Repository、Service、Client、Adapter。
+- Request DTO、Response DTO、Form、ViewModel，除非它本身就是业务提交记录。
+- 临时缓存、分页对象、排序条件、查询参数。
+- 纯 join table，除非关系本身有业务属性或生命周期。
+
+### Property
+
+创建条件：
+
+- 描述对象的身份、状态、分类、时间、数量、金额、位置、归属或业务含义。
+- 被查询、筛选、排序、展示、校验或用于权限判断。
+- 参与动作输入、动作结果、业务规则、关系或函数。
+
+关键约束：
+
+- 主键必须稳定、唯一，不应使用可变业务状态。
+- 枚举必须列出允许值。
+- 金额、邮箱、国家码、百分比等领域字段优先建 `valueTypes`。
+- 派生字段必须说明 derivation 或引用 Function。
+- 敏感字段必须标注 `sensitivity`。
+
+### Link Type
+
+创建条件：
+
+- 两个 Object Types 之间存在业务关系。
+- 关系会被查询、导航、展示、授权、动作或函数使用。
+- 关系有方向、基数、生命周期或自身属性。
+
+关键约束：
+
+- Link Type 必须连接 Object Type，不连接裸 Property。
+- 必须写 `cardinality`、`directionality`、`reverseDisplayName`。
+- many-to-many 关系若有业务属性或生命周期，考虑提升为 Object Type。
+
+### Action Type
+
+创建条件：
+
+- 创建、更新、删除对象，或建立/删除链接。
+- 表达明确业务意图，如 approve、assign、cancel、capture、submit、close。
+- 包含权限、校验、审批、通知或外部系统调用。
+
+不要创建：
+
+- 只读操作，如 get、list、search、export。
+- 单纯 getter、setter、helper。
+- 每个字段一个 action 的机械拆分。
+
+### Function
+
+创建条件：
+
+- 可复用业务逻辑。
+- 根据对象和关系计算、校验、聚合、评分、排序、推荐或授权。
+- 支撑 Action Type、派生 Property、API、报表或 agent 工具能力。
+
+不要创建：
+
+- 简单 getter/setter。
+- 纯 mapper、serializer、framework helper。
+- 没有业务语义的一次性 glue code。
+
+## 质量检查
+
+交付前检查：
+
+- Object Type 是否代表业务概念，而不是技术结构。
+- 每个 Object Type 是否有稳定主键和标题属性。
+- Property 是否有类型、必填性、空值语义、敏感性和证据。
+- Link Type 是否有方向、基数和反向名称。
+- Action Type 是否表达业务动作，而不是字段更新。
+- Function 是否是可复用业务逻辑，而不是 helper。
+- 每个重要判断是否有 source evidence。
+- 不确定问题是否进入 `openQuestions`。
+- YAML 中面向人类阅读的内容是否为中文。
+
+常见反模式：
+
+- `System Silo`：按系统/服务/数据库边界建模。
+- `Department Silo`：不同团队重复创建同一业务对象。
+- `Kitchen Sink`：把所有字段塞进一个对象。
+- `God Object`：一个对象承担过多职责。
+- `Action Sprawl`：为每个字段创建一个 action。
+
+## 最终回复
+
+完成后，最终回复只需说明：
+
+- 目标 codebase 的 `.ontology/` 路径。
+- 已生成或更新的文件列表。
+- 核心对象、关系、动作、函数摘要。
+- open questions 数量及最高优先级问题。
+- 质量检查是否通过。
+
+不要在最终回复中粘贴完整 YAML，除非用户明确要求。

package/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Codebase Ontology"
+  short_description: "为代码库生成 .ontology 五要素 YAML 文档"
+  default_prompt: "使用 $codebase-ontology 为当前代码库生成 .ontology 五要素 YAML 文档。"

package/bin/codebase-ontology.js

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const SKILL_NAME = "codebase-ontology";
+const PACKAGE_ROOT = path.resolve(__dirname, "..");
+const SKILL_ENTRIES = ["SKILL.md", "references", "agents"];
+
+function usage() {
+  console.log(`codebase-ontology
+
+Usage:
+  codebase-ontology install [--agent codex|claude|all] [--scope global|project] [--target-dir DIR] [--project-dir DIR] [--dry-run] [--force]
+  codebase-ontology uninstall [--agent codex|claude|all] [--scope global|project] [--target-dir DIR] [--project-dir DIR] [--dry-run] [--yes]
+  codebase-ontology doctor [--project-dir DIR]
+  codebase-ontology --help
+
+Defaults:
+  --agent all
+  --scope global
+  --project-dir current directory
+
+Default destinations:
+  Codex global:       ~/.codex/skills/codebase-ontology
+  Codex project:      <project>/.codex/skills/codebase-ontology
+  Claude Code global: ~/.claude/skills/codebase-ontology
+  Claude Code project:<project>/.claude/skills/codebase-ontology
+`);
+}
+
+function parseArgs(argv) {
+  const opts = {
+    command: "help",
+    agent: "all",
+    scope: "global",
+    projectDir: process.cwd(),
+    targetDir: null,
+    dryRun: false,
+    force: false,
+    yes: false
+  };
+
+  if (argv.length > 0 && !argv[0].startsWith("-")) {
+    opts.command = argv.shift();
+  }
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    switch (arg) {
+      case "--agent":
+        opts.agent = requireValue(argv, ++i, arg);
+        break;
+      case "--scope":
+        opts.scope = requireValue(argv, ++i, arg);
+        break;
+      case "--target-dir":
+        opts.targetDir = path.resolve(expandHome(requireValue(argv, ++i, arg)));
+        break;
+      case "--project-dir":
+        opts.projectDir = path.resolve(expandHome(requireValue(argv, ++i, arg)));
+        break;
+      case "--dry-run":
+        opts.dryRun = true;
+        break;
+      case "--force":
+        opts.force = true;
+        break;
+      case "--yes":
+      case "-y":
+        opts.yes = true;
+        break;
+      case "--help":
+      case "-h":
+        opts.command = "help";
+        break;
+      default:
+        fail(`Unknown option: ${arg}`);
+    }
+  }
+
+  if (!["help", "install", "uninstall", "doctor"].includes(opts.command)) {
+    fail(`Unknown command: ${opts.command}`);
+  }
+  if (!["codex", "claude", "all"].includes(opts.agent)) {
+    fail(`Invalid --agent: ${opts.agent}`);
+  }
+  if (!["global", "project"].includes(opts.scope)) {
+    fail(`Invalid --scope: ${opts.scope}`);
+  }
+
+  return opts;
+}
+
+function requireValue(argv, index, flag) {
+  const value = argv[index];
+  if (!value || value.startsWith("-")) {
+    fail(`${flag} requires a value`);
+  }
+  return value;
+}
+
+function expandHome(p) {
+  if (p === "~") return os.homedir();
+  if (p.startsWith("~/")) return path.join(os.homedir(), p.slice(2));
+  return p;
+}
+
+function selectedAgents(agent) {
+  return agent === "all" ? ["codex", "claude"] : [agent];
+}
+
+function skillsRoot(agent, scope, projectDir) {
+  if (scope === "global") {
+    if (agent === "codex") return path.join(os.homedir(), ".codex", "skills");
+    if (agent === "claude") return path.join(os.homedir(), ".claude", "skills");
+  }
+  if (agent === "codex") return path.join(projectDir, ".codex", "skills");
+  if (agent === "claude") return path.join(projectDir, ".claude", "skills");
+  fail(`Unsupported agent: ${agent}`);
+}
+
+function destinations(opts) {
+  if (opts.targetDir) {
+    return [{ agent: "custom", root: opts.targetDir, dest: path.join(opts.targetDir, SKILL_NAME) }];
+  }
+  return selectedAgents(opts.agent).map((agent) => {
+    const root = skillsRoot(agent, opts.scope, opts.projectDir);
+    return { agent, root, dest: path.join(root, SKILL_NAME) };
+  });
+}
+
+function install(opts) {
+  for (const target of destinations(opts)) {
+    console.log(`${opts.dryRun ? "[dry-run] " : ""}Install ${SKILL_NAME} -> ${target.dest}`);
+    if (opts.dryRun) continue;
+
+    if (fs.existsSync(target.dest)) {
+      if (!opts.force) {
+        console.log(`  Exists; updating in place. Use --force to replace cleanly.`);
+      } else {
+        fs.rmSync(target.dest, { recursive: true, force: true });
+      }
+    }
+
+    fs.mkdirSync(target.dest, { recursive: true });
+    for (const entry of SKILL_ENTRIES) {
+      copyRecursive(path.join(PACKAGE_ROOT, entry), path.join(target.dest, entry));
+    }
+  }
+}
+
+function uninstall(opts) {
+  if (!opts.yes && !opts.dryRun) {
+    fail("Refusing to uninstall without --yes. Re-run with --yes or --dry-run.");
+  }
+  for (const target of destinations(opts)) {
+    console.log(`${opts.dryRun ? "[dry-run] " : ""}Remove ${target.dest}`);
+    if (!opts.dryRun) {
+      fs.rmSync(target.dest, { recursive: true, force: true });
+    }
+  }
+}
+
+function doctor(opts) {
+  console.log(`Package root: ${PACKAGE_ROOT}`);
+  for (const agent of ["codex", "claude"]) {
+    for (const scope of ["global", "project"]) {
+      const root = skillsRoot(agent, scope, opts.projectDir);
+      const dest = path.join(root, SKILL_NAME);
+      const status = fs.existsSync(path.join(dest, "SKILL.md")) ? "installed" : "missing";
+      console.log(`${agent.padEnd(6)} ${scope.padEnd(7)} ${status.padEnd(9)} ${dest}`);
+    }
+  }
+}
+
+function copyRecursive(src, dest) {
+  const stat = fs.statSync(src);
+  if (stat.isDirectory()) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const child of fs.readdirSync(src)) {
+      copyRecursive(path.join(src, child), path.join(dest, child));
+    }
+    return;
+  }
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(src, dest);
+}
+
+function fail(message) {
+  console.error(`Error: ${message}`);
+  process.exit(1);
+}
+
+const opts = parseArgs(process.argv.slice(2));
+
+if (opts.command === "help") {
+  usage();
+} else if (opts.command === "install") {
+  install(opts);
+} else if (opts.command === "uninstall") {
+  uninstall(opts);
+} else if (opts.command === "doctor") {
+  doctor(opts);
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@zhaiye/codebase-ontology",
+  "version": "0.1.0",
+  "description": "Agent skill for generating codebase ontology YAML files.",
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "codebase-ontology": "bin/codebase-ontology.js"
+  },
+  "files": [
+    "SKILL.md",
+    "README.md",
+    "LICENSE",
+    "agents",
+    "references",
+    "bin"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/zhaiyeact/codebase_ontology.git"
+  },
+  "bugs": {
+    "url": "https://github.com/zhaiyeact/codebase_ontology/issues"
+  },
+  "homepage": "https://github.com/zhaiyeact/codebase_ontology#readme",
+  "keywords": [
+    "agent",
+    "skill",
+    "ontology",
+    "codex",
+    "claude-code"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/references/ontology-output-structure.md

@@ -0,0 +1,609 @@
+# Ontology 输出结构参考
+
+当使用 `codebase-ontology` skill 写入实际 `.ontology/` 文件时，读取本文件。
+
+本文件只定义输出结构、模板和示例，不包含外部参考资料。
+
+## 0. 输出语言要求
+
+生成到目标 codebase `.ontology/` 下的 YAML 文件，内容语言必须为中文。
+
+必须写成中文的值：
+
+- `displayName`
+- `description`
+- `notes`
+- `question`
+- `suggestedResolution`
+- `qualityChecks.*.notes`
+- `guide.definition`
+- object、property、link、action、function 的业务语义描述
+- `.ontology/README.md` 中的人类可读内容
+
+允许保持原文的值：
+
+- YAML schema key。
+- 稳定机器 ID。
+- 代码路径和 symbol。
+- API path。
+- 数据库表名、列名和外键名。
+- 代码中已有的枚举值、状态值和常量值。
+- 第三方系统名称。
+
+示例：`id: calculateOrderTotal` 可以保持英文，但 `displayName` 应写成 `计算订单总额`，`description` 应写成中文。
+
+## 1. 目录结构
+
+```text
+<codebase-root>/
+  .ontology/
+    README.md
+    index.yaml
+    object-types/
+      object-types.yaml
+    properties/
+      properties.yaml
+    link-types/
+      link-types.yaml
+    action-types/
+      action-types.yaml
+    functions/
+      functions.yaml
+```
+
+## 2. index.yaml
+
+```yaml
+metadata:
+  ontologyId: codebaseOntology
+  name: 代码库 Ontology
+  description: 从当前代码库抽取的业务 Ontology。
+  generatedAt: "YYYY-MM-DD"
+  generatedBy: "codex"
+  codebase:
+    name: ""
+    rootPath: ""
+    repositoryUrl: ""
+    commit: ""
+  scope:
+    includedPaths: []
+    excludedPaths: []
+    assumptions: []
+
+files:
+  objectTypes: .ontology/object-types/object-types.yaml
+  properties: .ontology/properties/properties.yaml
+  linkTypes: .ontology/link-types/link-types.yaml
+  actionTypes: .ontology/action-types/action-types.yaml
+  functions: .ontology/functions/functions.yaml
+
+summary:
+  domains: []
+  objectTypeCount: 0
+  propertyCount: 0
+  linkTypeCount: 0
+  actionTypeCount: 0
+  functionCount: 0
+  openQuestionCount: 0
+
+qualityStatus:
+  passed: false
+  blockingIssues: []
+```
+
+## 3. 通用证据格式
+
+```yaml
+sourceEvidence:
+  - id: evidenceId
+    kind: file | symbol | endpoint | database | test | documentation | inferred
+    path: string
+    symbol: string | null
+    lines: string | null
+    excerpt: string
+    notes: string
+```
+
+要求：
+
+- `path` 使用相对 codebase 根目录的路径。
+- `excerpt` 只放短片段。
+- 推断内容使用 `kind: inferred`，并在 `notes` 解释依据。
+
+## 4. object-types/object-types.yaml
+
+```yaml
+metadata:
+  fileType: objectTypes
+  generatedAt: "YYYY-MM-DD"
+  codebaseRoot: ""
+
+guide:
+  definition: Object Type 用于建模真实业务世界中的实体或事件。
+
+items:
+  - id: objectTypeId
+    displayName: 对象类型名称
+    pluralDisplayName: 对象类型复数名称
+    category: entity | event | document | actor | configuration | metric
+    description: 该对象类型的业务含义。
+    aliases: []
+    domain: domainId
+    primaryKey: id
+    titleProperty: name
+    lifecycle:
+      states: []
+      stateProperty: null
+      createdByActions: []
+      modifiedByActions: []
+      deletedByActions: []
+    implements: []
+    properties:
+      - propertyId
+    links:
+      outgoing: []
+      incoming: []
+    actions: []
+    functions: []
+    excludedFields:
+      - field: ""
+        reason: ""
+        sourceEvidence: []
+    sourceEvidence: []
+    confidence: high | medium | low
+
+sourceEvidence: []
+openQuestions: []
+qualityChecks:
+  objectTypesHavePrimaryKeys:
+    passed: false
+    notes: ""
+```
+
+示例：
+
+```yaml
+items:
+  - id: order
+    displayName: 订单
+    pluralDisplayName: 订单
+    category: entity
+    description: 客户购买一个或多个商品时形成的商业请求。
+    aliases:
+      - OrderEntity
+      - orders
+    domain: ordering
+    primaryKey: orderId
+    titleProperty: orderNumber
+    lifecycle:
+      states:
+        - draft
+        - placed
+        - paid
+        - fulfilled
+        - cancelled
+      stateProperty: status
+      createdByActions:
+        - placeOrder
+      modifiedByActions:
+        - cancelOrder
+        - capturePayment
+      deletedByActions: []
+    implements:
+      - auditable
+    properties:
+      - orderId
+      - orderNumber
+      - status
+      - totalAmount
+    links:
+      outgoing:
+        - orderContainsOrderLine
+        - orderHasPayment
+      incoming:
+        - customerPlacesOrder
+    actions:
+      - placeOrder
+      - cancelOrder
+      - capturePayment
+    functions:
+      - calculateOrderTotal
+      - canCancelOrder
+    excludedFields:
+      - field: internalSyncVersion
+        reason: 仅用于实现层同步的字段，不属于业务属性。
+        sourceEvidence:
+          - orderEntity
+    sourceEvidence:
+      - orderEntity
+      - orderMigration
+      - orderStateTransitionTests
+    confidence: high
+```
+
+## 5. properties/properties.yaml
+
+```yaml
+metadata:
+  fileType: properties
+  generatedAt: "YYYY-MM-DD"
+  codebaseRoot: ""
+
+guide:
+  definition: Property 用于建模对象类型的业务特征。
+
+items:
+  - id: propertyId
+    objectType: objectTypeId
+    displayName: 属性名称
+    description: 该属性的业务含义。
+    type: string | integer | long | decimal | float | double | boolean | date | timestamp | enum | array | object | struct | geoPoint | geoShape | attachment | mediaReference | timeSeries
+    required: false
+    nullable: true
+    unique: false
+    source: stored | derived | computed | external | writeback
+    sensitivity: public | internal | confidential | restricted
+    constraints: {}
+    derivation: null
+    sourceEvidence: []
+    confidence: high | medium | low
+
+valueTypes: []
+sharedProperties: []
+sourceEvidence: []
+openQuestions: []
+qualityChecks:
+  propertiesHaveTypes:
+    passed: false
+    notes: ""
+```
+
+示例：
+
+```yaml
+items:
+  - id: status
+    objectType: order
+    displayName: 状态
+    description: 订单当前所处的生命周期状态。
+    type: enum
+    required: true
+    nullable: false
+    unique: false
+    source: stored
+    sensitivity: internal
+    constraints:
+      allowedValues:
+        - draft
+        - placed
+        - paid
+        - fulfilled
+        - cancelled
+    derivation: null
+    sourceEvidence:
+      - orderStatusEnum
+      - orderStateTransitionTests
+    confidence: high
+
+  - id: totalAmount
+    objectType: order
+    displayName: 订单总金额
+    description: 所有订单明细在折扣后的总金额。
+    type:
+      valueType: money
+    required: true
+    nullable: false
+    unique: false
+    source: derived
+    sensitivity: internal
+    constraints:
+      minimum: 0
+    derivation:
+      function: calculateOrderTotal
+    sourceEvidence:
+      - calculateOrderTotalFunction
+    confidence: high
+```
+
+## 6. link-types/link-types.yaml
+
+```yaml
+metadata:
+  fileType: linkTypes
+  generatedAt: "YYYY-MM-DD"
+  codebaseRoot: ""
+
+guide:
+  definition: Link Type 用于建模对象类型之间的业务关系。
+
+items:
+  - id: sourceRelatesToTarget
+    displayName: 源对象关联目标对象
+    description: 该关系的业务含义。
+    fromObjectType: sourceObject
+    toObjectType: targetObject
+    reverseDisplayName: 目标对象被源对象关联
+    cardinality: oneToOne | oneToMany | manyToOne | manyToMany
+    directionality: directed | bidirectional
+    required: false
+    properties: []
+    backing:
+      kind: foreignKey | joinTable | objectReference | eventReference | inferred
+      details: ""
+    sourceEvidence: []
+    confidence: high | medium | low
+
+sourceEvidence: []
+openQuestions: []
+qualityChecks:
+  linksHaveCardinality:
+    passed: false
+    notes: ""
+```
+
+示例：
+
+```yaml
+items:
+  - id: customerPlacesOrder
+    displayName: 客户下订单
+    description: 一个客户创建或提交一个订单。
+    fromObjectType: customer
+    toObjectType: order
+    reverseDisplayName: 订单由客户提交
+    cardinality: oneToMany
+    directionality: directed
+    required: true
+    properties: []
+    backing:
+      kind: foreignKey
+      details: orders.customer_id references customers.id
+    sourceEvidence:
+      - orderMigration
+      - orderEntity
+    confidence: high
+```
+
+## 7. action-types/action-types.yaml
+
+```yaml
+metadata:
+  fileType: actionTypes
+  generatedAt: "YYYY-MM-DD"
+  codebaseRoot: ""
+
+guide:
+  definition: Action Type 用于建模会改变对象、属性或链接的业务操作。
+
+items:
+  - id: performBusinessAction
+    displayName: 执行业务动作
+    description: 该动作的业务意图和结果。
+    actors:
+      - role: ""
+        description: ""
+    targets:
+      - objectType: objectTypeId
+        parameter: objectId
+        cardinality: single | set
+    inputParameters:
+      - id: objectId
+        displayName: 对象 ID
+        type: string
+        required: true
+        nullable: false
+        description: ""
+        constraints: {}
+    rules:
+      preconditions: []
+      validations: []
+      authorization: []
+    effects:
+      creates: []
+      updates: []
+      deletes: []
+      links: []
+      unlinks: []
+    sideEffects:
+      notifications: []
+      webhooks: []
+      externalCalls: []
+      scheduledJobs: []
+    reversible: false
+    usedFunctions: []
+    sourceEvidence: []
+    confidence: high | medium | low
+
+sourceEvidence: []
+openQuestions: []
+qualityChecks:
+  actionsDescribeBusinessIntent:
+    passed: false
+    notes: ""
+```
+
+示例：
+
+```yaml
+items:
+  - id: cancelOrder
+    displayName: 取消订单
+    description: 取消一个尚未履约完成的订单。
+    actors:
+      - role: customer
+        description: 客户取消自己的订单。
+      - role: supportAgent
+        description: 客服人员代客户取消订单。
+    targets:
+      - objectType: order
+        parameter: orderId
+        cardinality: single
+    inputParameters:
+      - id: orderId
+        displayName: 订单 ID
+        type: string
+        required: true
+        nullable: false
+        description: 需要取消的订单。
+        constraints: {}
+      - id: reason
+        displayName: 取消原因
+        type: string
+        required: false
+        nullable: true
+        description: 可选的取消原因。
+        constraints:
+          maxLength: 500
+    rules:
+      preconditions:
+        - 订单状态必须是 draft、placed 或 paid。
+      validations:
+        - 已履约完成的订单不能取消。
+      authorization:
+        - 执行人必须拥有该订单，或具有 supportAgent 角色。
+    effects:
+      creates: []
+      updates:
+        - objectType: order
+          property: status
+          value: cancelled
+      deletes: []
+      links: []
+      unlinks: []
+    sideEffects:
+      notifications:
+        - 发送订单取消通知。
+      webhooks: []
+      externalCalls:
+        - 如果订单已收款，向支付供应商请求退款。
+      scheduledJobs: []
+    reversible: false
+    usedFunctions:
+      - canCancelOrder
+    sourceEvidence:
+      - cancelOrderEndpoint
+      - orderServiceCancelOrder
+      - orderStateTransitionTests
+    confidence: high
+```
+
+## 8. functions/functions.yaml
+
+```yaml
+metadata:
+  fileType: functions
+  generatedAt: "YYYY-MM-DD"
+  codebaseRoot: ""
+
+guide:
+  definition: Function 用于建模可复用的业务逻辑。
+
+items:
+  - id: calculateBusinessValue
+    displayName: 计算业务值
+    description: 可复用的业务逻辑。
+    inputs:
+      - id: inputId
+        type: string
+        required: true
+    outputs:
+      type: string
+      description: ""
+    reads:
+      objectTypes: []
+      properties: []
+      linkTypes: []
+    writes:
+      objectTypes: []
+      properties: []
+      linkTypes: []
+    usedBy:
+      actionTypes: []
+      properties: []
+      endpoints: []
+      jobs: []
+    determinism: deterministic | timeDependent | userDependent | externalDependent
+    externalDependencies: []
+    errorCases: []
+    sourceEvidence: []
+    confidence: high | medium | low
+
+sourceEvidence: []
+openQuestions: []
+qualityChecks:
+  functionsAreReusableBusinessLogic:
+    passed: false
+    notes: ""
+```
+
+示例：
+
+```yaml
+items:
+  - id: calculateOrderTotal
+    displayName: 计算订单总额
+    description: 根据订单明细计算订单总金额。
+    inputs:
+      - id: orderId
+        type: string
+        required: true
+    outputs:
+      type:
+        valueType: money
+      description: 该订单的总金额。
+    reads:
+      objectTypes:
+        - order
+        - orderLine
+      properties:
+        - orderLine.quantity
+        - orderLine.unitPrice
+      linkTypes:
+        - orderContainsOrderLine
+    writes:
+      objectTypes: []
+      properties: []
+      linkTypes: []
+    usedBy:
+      actionTypes:
+        - placeOrder
+        - capturePayment
+      properties:
+        - order.totalAmount
+      endpoints: []
+      jobs: []
+    determinism: deterministic
+    externalDependencies: []
+    errorCases:
+      - 当订单没有明细时返回校验错误。
+    sourceEvidence:
+      - calculateOrderTotalFunction
+      - orderTotalTests
+    confidence: high
+```
+
+## 9. README.md 摘要模板
+
+```markdown
+# 代码库 Ontology
+
+生成时间：YYYY-MM-DD  
+代码库：<name>
+
+## 摘要
+
+- Object Types: N
+- Properties: N
+- Link Types: N
+- Action Types: N
+- Functions: N
+- Open Questions: N
+
+## 核心业务域
+
+...
+
+## 主要未决问题
+
+...
+```