docs: align README/copilot pages with the shipped skills-only surface (#589) - #611
Merged
Conversation
…#589) The README claimed "2 AI agents (sales-copilot, service-copilot), 20 flows, 5 sharing rules" seventy lines above a layout block that correctly described a skills-only surface with 23 flows. Both now state the numbers that objectstack.config.ts actually registers: 0 app-owned agents, 6 skills, 23 flows, 9 sharing rules, 8 datasets. Rewrite the six published copilot pages (en/zh-Hans/zh-Hant) as skill docs at their existing URLs. The personas were retired in #512; the capability ships as six skills on the platform `ask` assistant. Activation is documented from each skill's real triggerConditions, and writes are named as the HotCRM actions the skills call (convert_lead, schedule_followup, escalate_case, close_case) instead of inline buttons that do not exist. Follow the rename through the AI Copilot index, the Skills and Knowledge Bases pages, the glossary's "Agent (AI)" entry, the customization guide (which told developers to edit the long-deleted src/agents/sales-copilot.agent.ts) and every inbound link label. live-schema.* is left untouched — it is #606's scope. Banner the archived Salesforce comparison: it describes a ~148-object, 13-package architecture and marks sla_policy/queue/email_to_case/pricebook as implemented when none exist, so its "~95% parity" headline misled anyone evaluating the repo. Correct docs/ARCHITECTURE.md: drop the deleted src/agents and the never-created src/cubes from the diagram, 1.0.5 -> 2.2.2, and remove the `ai` capability from `requires` (removed in 2.2.0 because it is fail-fast under ObjectStack 16). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019SS7C5SXpniKeCApxgARyf
|
The latest updates on your projects. Learn more about Vercel for GitHub. |
github-actions
Bot
added
the
documentation
os-zhuang
marked this pull request as ready for review
August 2, 2026 11:32
This was referenced Aug 6, 2026
yinlianghui
added a commit
to yinlianghui/hotcrm
that referenced
this pull request
Aug 10, 2026
…-ai#976, objectstack-ai#977) (objectstack-ai#987) * docs(analytics): write the landing page to source and retire the cube vocabulary (objectstack-ai#976, objectstack-ai#977) `content/docs/analytics/index.mdx` is the first screen a reader of the analytics docs sees, and every count on it named something else. Six claims, all three locales, rewritten against `src/`: - 4 cubes (Sales, Pipeline, Service, Marketing) -> no cube of this app's own; the semantic layer is the nine datasets in `src/datasets/`, compiled into cubes by the analytics service (ADR-0021). The four names hit nothing. - 4 dashboards -> five; Sales Activity was missing. - "10+ standard reports across leads, deals, cases, contracts" -> exactly ten, and none of them is a contract report: no dataset reads `crm_contract`, so none can be built. - a rep running *Pipeline by Stage* -> **Opportunities by Stage**, with the name's two real identities (a shared dashboard tile, a chart title) written the way PR objectstack-ai#975 wrote them on the reports page. - the **Analytics** navigation group -> **Insights**, with the five entries the app pins to it; nothing in the sidebar is called Dashboards/Reports/Cubes. - "the AI Copilot can read directly from cubes" -> what this app declares (no skill names a dataset, cube or measure; the data-question skill aggregates over records), leaving the platform side undecided rather than asserted. The `/docs/ai-copilot/sales-copilot` link the issue reported as dangling is not: objectstack-ai#589 / PR objectstack-ai#611 renamed the link text and the target page has been there throughout. Left as is, and pinned. Eight further pages carried the same retired vocabulary (objectstack-ai#977): whats-new now lists the nine datasets; for-developers draws `datasets/` instead of the `src/cubes/` directory removed in objectstack-ai#492; performance-and-limits and faq state the refresh cadence the app really declares (each dashboard's own `refreshInterval` - 60s / 180s / 300s) instead of an "every 5 min incremental, nightly full" figure nothing in `src/` configures, and no longer promise a manual refresh button no dashboard declares; pipeline-management, introduction, fork-hotcrm and sandbox-and-releases were renames only. The glossary's definition of the cube concept is deliberately untouched. `test/docs-analytics-vocabulary.test.ts` derives every count and product name on these pages from `src/` and fails when the app and the page disagree. Reverse verification: 25 of its 39 rules go red on the pre-fix tree, green after. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VHrPAGEgFDoHjphqYG4BMa * docs(analytics): name the forecast figures by their record and dataset labels The landing page's Copilot section cited Commit / Quota / Closed / Pipeline as figures on the forecast record. Three of the four are: closed_amount is labelled **Closed Won** on crm_forecast and only becomes **Closed** as a measure on the Forecast Metrics dataset. Say both, so the name a reader sees on the record and the name they select in a report each appear where they belong. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VHrPAGEgFDoHjphqYG4BMa --------- Co-authored-by: Claude <noreply@anthropic.com>
yinlianghui
added a commit
to yinlianghui/hotcrm
that referenced
this pull request
Aug 10, 2026
…stack-ai#1001) * docs: 全站去人格化 Copilot 称呼，并把版本号钉到 manifest (objectstack-ai#612) objectstack-ai#512 退役了应用自有的两个 agent，ADR-0063 §2 把 AI 表面收敛为 skills-only； objectstack-ai#589 / PR objectstack-ai#611 据此重写了 content/docs/ai-copilot/*。但产品文档树的其余部分 没有跟上：29 个页面（三语）仍在散文里把助手称作 "the Sales Copilot" / "the Service Copilot"，共 65 处。它们都没有声明 sales_copilot 这个 agent， 所以每一道门都是绿的——os validate 与 pnpm lint 走的是被授权的元数据， 从不打开一个段落。 按维护者 2026-08-04 对 objectstack-ai#612 的拍板，这些页面改称 "AI assistant" （zh-Hans / zh-Hant 用「AI 助手」），只换称呼、保留每句话的功能语义。措辞 遵循这些页面必须描述的架构：AI 能力由 objectstack-ai/cloud 侧的 agent 承载， HotCRM 提供的是附着在平台助手（ask）上的领域 skills，因此改写后没有任何一页 再暗示应用内存在独立 agent 实体。两个 zh index 页还留着 ## Sales Copilot / ## Service Copilot 标题，而其英文对应页早已改为 Sales AI skills / Service AI skills，现已对齐；whats-new.mdx 则是镜像情形——两个译文早已写作 "向助手询问"，只有英文页还在人格化。 12 个页面按名单保留这两个名字，每条都记了理由：objectstack-ai#611 写的 9 处 ai-copilot 退役说明，以及 3 个 whats-new v1.0 发布记录（如实记载那次发布交付了什么）。 test/docs-drift.test.ts 随单加两条规则，避免出现第三轮清理： - 人格规则：content/docs/** 下不得再出现这两个称呼。扫描前先归一化软换行与 引用块续行符——两处线上命中本就跨行（the Sales\n> Copilot、ask the Sales\nCopilot），而按行 grep（本 issue 原始清点所用的方式）两处都读不到； 两个 CJK 字符之间的空白也会被去掉，因为 ai-copilot/index.zh-Hant.mdx 把 「服務 Copilot」断在了服与務之间。三道防空转：遍历必须扫到真实文档树、 每条豁免必须仍覆盖活的命中、探针用例断言检测器能读出全部六种拼写在每种 换行形态下的样子——没有最后这条，一个失效的检测器会报出"干净的树"， 读起来与成功一模一样。 - 版本号规则：docs/RELEASE_STRATEGY.md 自 v1 起一直印着 1.0.5，而 manifest 声明的是 2.2.2——在发布者唯一会信的那一页上落后了整整一个大版本。现改为 2.2.2，并从 objectstack.config.ts 的 manifest.version 抽取该值，断言 RELEASE_STRATEGY.md、STATUS.md、ARCHITECTURE.md、README.md 都印它，另加 package.json 一致性检查——正是 RELEASE_STRATEGY.md 自己的 Version Sources 一节要求保持的对齐。 反向验证（改前红 / 改后绿，方向为事前预测）：改前人格规则报 29 页、版本号 行规则报 "docs/RELEASE_STRATEGY.md states 1.0.5, the manifest declares 2.2.2"；改后 docs-drift.test.ts 57/57 全绿。 仅文档、散文与测试：未动元数据、未动 src/ 行为、未动依赖。 Fixes objectstack-ai#612 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VHrPAGEgFDoHjphqYG4BMa * docs(test): 把人格守卫注释里的计数拆成豁免与非豁免两半 (objectstack-ai#612) 原句写作「39 product pages went on calling the assistant …79 occurrences」， 把全量面（39 页 / 79 处，含 12 页历史性豁免）说成了产品散文面。守卫下方的反向 验证一节写的是 29 页 / 65 处，两个数字放在一起会让下一位读者以为其中一个是错的。 现在把两半分开写明：79 处 / 39 页里，14 处（12 页）是退役史、归 HISTORICAL； 其余 65 处（29 页）才是本单改写的活散文。 仅注释，无行为变化。 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VHrPAGEgFDoHjphqYG4BMa --------- Co-authored-by: Claude <noreply@anthropic.com>
yinlianghui
added a commit
to yinlianghui/hotcrm
that referenced
this pull request
Aug 10, 2026
…the home card (objectstack-ai#1005) The `ai_briefing` card on `sales_home_page` still read "Ask the Sales Copilot" and pointed at "the floating Copilot (bottom-right)". Both are wrong in live UI copy a user sees today: - The `sales_copilot` agent was retired in objectstack-ai#512 and ADR-0063 §2 made the app surface skills-only. Per the maintainer's 2026-08-04 ruling on objectstack-ai#612 (Option A) plus the architecture note that followed it, AI capability is implemented by agents in objectstack-ai/cloud and HotCRM contributes domain skills — so the card named an entity this app does not contain. - The entry point contradicted the docs: `content/docs/ai-copilot/index.mdx` documents "the chat panel the platform opens from the right edge of every page" (objectstack-ai#611 / PR objectstack-ai#1001), not a floating bottom-right widget. Card behaviour, position and functional promise are unchanged; only the name and the directions moved. Card copy has no locale keys — the translation contract exposes page label/description/title/subtitle only — so the value chain is the literal in `home.page.ts` straight into `dist/objectstack.json`, which now carries zero occurrences of "Copilot" in any spelling. Pinned in `test/metadata-references.test.ts` alongside the other retired -agent guards. The pin is deliberately scoped to this one card: a scan-surface rule over every user-visible string in `src/` is a separate question and is filed on its own. Refs objectstack-ai#1002. Claude-Session: https://claude.ai/code/session_01VHrPAGEgFDoHjphqYG4BMa Co-authored-by: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #589
Description
纯文档变更，不触碰任何 metadata。本 PR 解决四类文档漂移：README 自相矛盾的数量、把已退役 agent 当作在售能力描述的已发布页面、缺少免责声明的归档对比文档，以及过时的架构文档。
所有数字均以当前
origin/main的objectstack.config.ts为准，并由pnpm validate的输出复核。Type of Change
Related Issues
Fixes #589
Related to #512 (agent 退役), #607 (
defaultAgent改绑平台ask), #606 (live-schema 演示路径 —— 不在本 PR 范围)Changes Made
1. README 数字统一
README.md:8和:60声称 "2 AI agents (sales-copilot, service-copilot)、20 flows、5 sharing rules"，而同一文件:131的仓库结构块正确地写着 skills-only surface, no agents 和 23 flows。真实数字取自objectstack.config.ts：ask）pnpm validate输出复核：15 Objects · 23 Flows · 4 Dashboards · 13 Actions · 12 Positions · 6 Permissions。2. copilot 页面改写为技能文档（6 个页面 + 关联页）
ai-copilot/{sales,service}-copilot.mdx（en / zh-Hans / zh-Hant）此前描述的是 #512 已退役的两个人格化 agent，例如 "It lives in the right-side chat panel and as inline buttons on lead, contact, account, and opportunity pages" —— 那些内联按钮并不存在。按 issue 的要求改写而非删除，URL 保持不变（
/docs/ai-copilot/sales-copilot等），避免站内外链接失效；仅title改为 Sales Skills / Service Skills / 销售技能 / 銷售技能。新内容全部有源可依：triggerConditions——lead_qualification→crm_lead；revenue_forecasting→crm_opportunity或dashboard；case_triage→crm_case；live_data/email_drafting/customer_360无限制。convert_lead、schedule_followup、escalate_case、close_case），取代原先虚构的 🎯 Qualify / 🚦 Triage / 📚 Find articles 按钮。连带修正的页面：
ai-copilot/index（"两个 Copilot" → 一个平台助手 + 六项技能的两种分组）、ai-copilot/skills、ai-copilot/knowledge-bases的 Used by 列、reference/glossary的 Agent (AI) 条目（原文直接断言 "The Sales Copilot and Service Copilot are agents"）、customization/ai-skills（原文让开发者去编辑早已删除的src/agents/sales-copilot.agent.ts，现改为导出 + 加入allSkills），以及sales/、service/、analytics/、guides/、getting-started/中全部指向这两页的链接文案。三语言同步。content/docs/ai-copilot/live-schema.*与scripts/wow1-live-schema.sh一行未动 —— 那是 #606 的范围。本 PR 的改写没有新增与其冲突的断言：新文案只陈述"能力以 skills 形式挂在平台助手上"这一 #607 已落地的事实。3. 归档对比文档加退役横幅
docs/archive/2026-02/SALESFORCE_FEATURE_COMPARISON.md描述的是 ~148 个对象、13 个 package 的另一套架构，把sla_policy/queue/email_to_case/pricebook标为"✅ Implemented"（当前树中一个都不存在），并宣称 ~95% Salesforce 功能对等。文件虽已归档但无任何提示，任何评估本仓库的人都会被误导。现以醒目横幅开头，说明它描述的是 pre-2.x 退役架构，并给出当前产品的真实规模与 README / ARCHITECTURE 的指引。4.
docs/ARCHITECTURE.md去陈旧化src/agents与从未存在的src/cubes，Analytics 分支改为src/datasets, src/dashboards, src/reports。1.0.5→2.2.2，并补上engines.protocol。requires列表移除ai（2.2.0 移除；ObjectStack 16 下它是 fail-fast 能力，声明会直接让开源版objectstack start启动中止），并附上原因说明。roles→positions，以及指向不存在的src/sharing/role-hierarchy.ts—— 按 ADR-0090 D3 改为src/sharing/positions.ts并说明层级已移除。Testing
pnpm test：Test Files 34 passed (34)，Tests 652 passed | 1 skipped (653)，含test/docs-drift.test.ts的仓库树漂移守卫（TREE_DOCS覆盖 README.md 与 docs/ARCHITECTURE.md）pnpm lint：1 warning(s), 13 suggestion(s)，与 base 一致，无新增pnpm build：✓ Build complete，dist/objectstack.json (1014.1 KB)pnpm validate：✓ Validation passed (1074ms)pnpm typecheck：无输出（通过）TREE_DOCS文件Checklist
.changeset/docs-align-retired-agents.md（patch）Additional Notes
范围之外的发现，已单独立 issue #612（未在本 PR 修复，遵循 Prime Directive #10）：
objectstack.config.ts:76的注释仍写着 "the two agents + skills still validate" —— 同一类漂移，但属于源码文件而非文档。docs/RELEASE_STRATEGY.md:14仍写Current version | 1.0.5（实际 2.2.2）。content/docs/下另有约 39 个产品页面（sales / service / revenue / reference / whats-new）在散文中把 "Sales Copilot" / "Service Copilot" 当作助手昵称使用（共约 90 处）。issue Docs alignment: README/copilot pages describe retired agents; archived Salesforce comparison lacks a retired-architecture banner #589 的问题 2 明确只列举了ai-copilot/{sales,service}-copilot.mdx这 6 个页面，且这批文件与 Wow #1 demo docs + script still POST the retiredsales_copilotagent #606 的范围有重叠，因此把全站改名作为独立议题另行处理更安全。这些散文并未断言存在名为sales_copilot的 agent，因此本 issue 的验收标准"没有已发布页面把 sales_copilot/service_copilot 描述为在售 agent"已经满足。content/docs/whats-new.mdx的 "What's in v1.0" 小节提到 Sales Copilot —— 该节是历史发布记录，与 CHANGELOG 同属史料，故保留（仅把中文版首屏现在时的营销文案 "向 Sales Copilot 询问" 与英文版对齐为"向助手询问"）。