From 1104f643e09218f9be871866c58fe463ecfffda5 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 6 Aug 2026 15:35:14 +0000 Subject: [PATCH] =?UTF-8?q?docs(customization):=20=E6=8C=89=E5=AE=9E?= =?UTF-8?q?=E5=86=B5=E9=87=8D=E7=94=BB=20customization/index=20=E7=9A=84?= =?UTF-8?q?=20src/=20=E7=9B=AE=E5=BD=95=E6=A0=91=E5=B9=B6=E7=BA=B3?= =?UTF-8?q?=E5=85=A5=20docs-drift=20=E5=AE=88=E5=8D=AB=20(#988)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit customization/index 三语页是 #984 的同型孪生：目录树画着 agents/、后缀表 列着 *.agent.ts，两者都随应用自带的两个 copilot 一起被 #512 移除。整树 逐目录对账后补上了真实存在却缺席的 hooks/、datasets/、mappings/、docs/、 interfaces/，:15 表格里已不存在的 "agent wiring" 按 skills barrel 实况改写。 修好后三语加入 test/docs-drift.test.ts 的 PRODUCT_TREE_DOCS——#984 在该处 留的注释正指向本单。TREE_DIAGRAM_DOCS 由该列表展开而来，故一处登记同时 覆盖 inline 与目录树两条轴。 Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01VHrPAGEgFDoHjphqYG4BMa --- .../docs-customization-index-src-tree.md | 26 +++++++++++++++++++ content/docs/customization/index.mdx | 15 +++++++---- content/docs/customization/index.zh-Hans.mdx | 15 +++++++---- content/docs/customization/index.zh-Hant.mdx | 15 +++++++---- test/docs-drift.test.ts | 18 ++++++++++--- 5 files changed, 71 insertions(+), 18 deletions(-) create mode 100644 .changeset/docs-customization-index-src-tree.md diff --git a/.changeset/docs-customization-index-src-tree.md b/.changeset/docs-customization-index-src-tree.md new file mode 100644 index 00000000..c32ffba8 --- /dev/null +++ b/.changeset/docs-customization-index-src-tree.md @@ -0,0 +1,26 @@ +--- +'hotcrm': patch +--- + +Redraw the customization landing page's `src/` tree from the real repository, and +put the page under the docs-drift tree guard. + +`content/docs/customization/index.mdx` (and both Chinese locales) is the twin of +the developer page fixed in #984: it drew an `agents/` branch in the `src/` tree +and listed `*.agent.ts` in the file-suffix table, both of which went away with +the two app-owned copilots. HotCRM authors skills and the agent comes from the +platform, so a reader following this page was being pointed at a directory and a +file suffix that no longer exist. + +The tree was reconciled directory by directory rather than only having the dead +branch cut out, so it now lists all eighteen directories `src/` actually +contains: `hooks/`, `datasets/`, `mappings/`, `docs/` and `interfaces/` were +real and missing from it, and every branch states what it actually holds. The +"What you can build" table billed the AI skills page as "Copilot skills and +agent wiring"; the wiring it referred to is gone, and exporting from the skills +barrel is the whole of it. + +The page then joins `PRODUCT_TREE_DOCS` in `test/docs-drift.test.ts`, the guard +#984 built for exactly this defect class and left a note in pointing at this +page. Membership covers both of that guard's axes at once, since the tree-diagram +list is derived from the product list. diff --git a/content/docs/customization/index.mdx b/content/docs/customization/index.mdx index 37a8fa45..654a9ea2 100644 --- a/content/docs/customization/index.mdx +++ b/content/docs/customization/index.mdx @@ -12,7 +12,7 @@ This section is for developers and technical implementers extending HotCRM with | Area | What it covers | | --- | --- | | [Extending objects](/docs/customization/extending-objects) | Fields, objects, hooks, flows, validation, sharing | -| [AI skills](/docs/customization/ai-skills) | Copilot skills and agent wiring | +| [AI skills](/docs/customization/ai-skills) | Skills for the platform assistant, and the barrel that registers them | | [UI extensions](/docs/customization/ui-extensions) | Pages, views, dashboards, actions | | [Testing and CI](/docs/customization/testing-and-ci) | Metadata validation and automated checks | @@ -22,22 +22,28 @@ HotCRM is a single ObjectStack app. Add or modify metadata under `src/`, then ex ```text src/ -├── objects/ # data model and object hooks +├── objects/ # *.object.ts schemas and *.hook.ts lifecycle logic +├── hooks/ # barrel that hands the object hooks to the stack ├── actions/ # UI actions and executable action bodies ├── flows/ # automation -├── agents/ # AI agents ├── skills/ # AI skills ├── apps/ ├── views/ ├── pages/ ├── dashboards/ ├── reports/ +├── datasets/ # dimensions and measures the dashboards and reports query +├── mappings/ # import column-to-field projections ├── profiles/ ├── sharing/ ├── translations/ -└── data/ +├── data/ # seed data +├── docs/ # package docs stating the business rules the flows implement +└── interfaces/ # shared types (an empty barrel today) ``` +HotCRM authors skills, not agents: the two app-owned copilots and the directory that held them were retired, and AI capability now comes from the platform assistant every ObjectStack environment provides. Exporting a skill from `src/skills/index.ts` is the whole wiring step. See [AI Skills](/docs/customization/ai-skills). + ## File suffix protocol | Suffix | What it defines | @@ -47,7 +53,6 @@ src/ | `*.actions.ts` | UI actions and executable actions | | `*.flow.ts` | Automation | | `*.skill.ts` | AI Copilot skill | -| `*.agent.ts` | AI agent | | `*.page.ts` | UI page | | `*.view.ts` | List or kanban view | | `*.dashboard.ts` | Dashboard | diff --git a/content/docs/customization/index.zh-Hans.mdx b/content/docs/customization/index.zh-Hans.mdx index 397874a6..c36e98a8 100644 --- a/content/docs/customization/index.zh-Hans.mdx +++ b/content/docs/customization/index.zh-Hans.mdx @@ -12,7 +12,7 @@ description: 用 ObjectStack 元数据、动作、流程、AI skills 和 UI 定 | 领域 | 内容 | | --- | --- | | [扩展对象](/zh-Hans/docs/customization/extending-objects) | 字段、对象、hooks、流程、校验、共享 | -| [AI skills](/zh-Hans/docs/customization/ai-skills) | Copilot skills 和 agent 接线 | +| [AI skills](/zh-Hans/docs/customization/ai-skills) | 面向平台助手的 skills，以及注册它们的 barrel | | [UI 扩展](/zh-Hans/docs/customization/ui-extensions) | 页面、视图、仪表盘、动作 | | [测试与 CI](/zh-Hans/docs/customization/testing-and-ci) | 元数据校验和自动化检查 | @@ -22,22 +22,28 @@ HotCRM 是一个单体 ObjectStack 应用。请在 `src/` 下新增或修改元 ```text src/ -├── objects/ # 数据模型和对象 hooks +├── objects/ # *.object.ts 模型和 *.hook.ts 生命周期逻辑 +├── hooks/ # 把对象 hooks 汇总交给 stack 的 barrel ├── actions/ # UI 动作和可执行动作体 ├── flows/ # 自动化 -├── agents/ # AI agents ├── skills/ # AI skills ├── apps/ ├── views/ ├── pages/ ├── dashboards/ ├── reports/ +├── datasets/ # 仪表盘和报表查询的维度与度量 +├── mappings/ # 数据导入的列到字段映射 ├── profiles/ ├── sharing/ ├── translations/ -└── data/ +├── data/ # 种子数据 +├── docs/ # 陈述流程所实现业务规则的应用文档 +└── interfaces/ # 共享类型（目前是空 barrel） ``` +HotCRM 只定义 skills，不定义 agent：应用自带的两个 copilot 及其所在目录已被移除，AI 能力来自每个 ObjectStack 环境都提供的平台助手。把 skill 从 `src/skills/index.ts` 导出就是全部的接线工作。参见 [AI Skills](/zh-Hans/docs/customization/ai-skills)。 + ## 文件后缀协议 | 后缀 | 定义 | @@ -47,7 +53,6 @@ src/ | `*.actions.ts` | UI 动作和可执行动作 | | `*.flow.ts` | 自动化 | | `*.skill.ts` | AI Copilot skill | -| `*.agent.ts` | AI agent | | `*.page.ts` | UI 页面 | | `*.view.ts` | 列表或看板视图 | | `*.dashboard.ts` | 仪表盘 | diff --git a/content/docs/customization/index.zh-Hant.mdx b/content/docs/customization/index.zh-Hant.mdx index ce61a3f3..2b74035a 100644 --- a/content/docs/customization/index.zh-Hant.mdx +++ b/content/docs/customization/index.zh-Hant.mdx @@ -12,7 +12,7 @@ description: 用 ObjectStack 中繼資料、動作、流程、AI skills 和 UI | 領域 | 內容 | | --- | --- | | [擴展物件](/zh-Hant/docs/customization/extending-objects) | 欄位、物件、hooks、流程、校驗、共享 | -| [AI skills](/zh-Hant/docs/customization/ai-skills) | Copilot skills 和 agent 接線 | +| [AI skills](/zh-Hant/docs/customization/ai-skills) | 面向平台助手的 skills，以及註冊它們的 barrel | | [UI 擴展](/zh-Hant/docs/customization/ui-extensions) | 頁面、視圖、儀表板、動作 | | [測試與 CI](/zh-Hant/docs/customization/testing-and-ci) | 中繼資料校驗和自動化檢查 | @@ -22,22 +22,28 @@ HotCRM 是一個單體 ObjectStack 應用。請在 `src/` 下新增或修改中 ```text src/ -├── objects/ # 資料模型和物件 hooks +├── objects/ # *.object.ts 模型和 *.hook.ts 生命週期邏輯 +├── hooks/ # 把物件 hooks 彙總交給 stack 的 barrel ├── actions/ # UI 動作和可執行動作體 ├── flows/ # 自動化 -├── agents/ # AI agents ├── skills/ # AI skills ├── apps/ ├── views/ ├── pages/ ├── dashboards/ ├── reports/ +├── datasets/ # 儀表板和報表查詢的維度與度量 +├── mappings/ # 資料匯入的欄位對應 ├── profiles/ ├── sharing/ ├── translations/ -└── data/ +├── data/ # 種子資料 +├── docs/ # 陳述流程所實作業務規則的應用文件 +└── interfaces/ # 共享型別（目前是空 barrel） ``` +HotCRM 只定義 skills，不定義 agent：應用自帶的兩個 copilot 及其所在目錄已被移除，AI 能力來自每個 ObjectStack 環境都提供的平台助手。把 skill 從 `src/skills/index.ts` 匯出就是全部的接線工作。參見 [AI Skills](/zh-Hant/docs/customization/ai-skills)。 + ## 檔案後綴協議 | 後綴 | 定義 | @@ -47,7 +53,6 @@ src/ | `*.actions.ts` | UI 動作和可執行動作 | | `*.flow.ts` | 自動化 | | `*.skill.ts` | AI Copilot skill | -| `*.agent.ts` | AI agent | | `*.page.ts` | UI 頁面 | | `*.view.ts` | 清單或看板視圖 | | `*.dashboard.ts` | 儀表板 | diff --git a/test/docs-drift.test.ts b/test/docs-drift.test.ts index a637a4e8..020fc75b 100644 --- a/test/docs-drift.test.ts +++ b/test/docs-drift.test.ts @@ -292,14 +292,26 @@ describe('maintainer docs do not point at directories that no longer exist', () * on a page is a pointer is an editorial fact about that page, so pages opt in * here one at a time. * - * `customization/index.{mdx,zh-Hans,zh-Hant}` draws the same tree and still - * carries the retired `agents/` entry plus a `*.agent.ts` row (#988); its three - * locales join both lists below with that fix. + * `customization/index.{mdx,zh-Hans,zh-Hant}` drew the same tree with the same + * retired `agents/` entry and `*.agent.ts` row; #988 redrew all three and they + * joined here, as the note left above by #984 anticipated. + * + * Membership costs a page something, and the customization page had to pay it: + * the inline check below refuses to pass vacuously, and that page named no + * `src//` inline at all — its one candidate, the golden rule "export from + * the relevant `src/**\/index.ts`", is a glob and matches nothing. What made it + * eligible is the barrel sentence #988 added under the tree, which names + * `src/skills/index.ts` outright. A page that only DRAWS a tree belongs in + * TREE_DIAGRAM_DOCS; being here additionally asserts it points into `src/` in + * prose. */ const PRODUCT_TREE_DOCS = [ 'content/docs/getting-started/for-developers.mdx', 'content/docs/getting-started/for-developers.zh-Hans.mdx', 'content/docs/getting-started/for-developers.zh-Hant.mdx', + 'content/docs/customization/index.mdx', + 'content/docs/customization/index.zh-Hans.mdx', + 'content/docs/customization/index.zh-Hant.mdx', ]; /** Every doc that DRAWS a `src/` tree — the form axis, maintainer and product alike. */