From 18aaea28061487d5cc86605848d150b847bfca89 Mon Sep 17 00:00:00 2001 From: marchtian Date: Sun, 1 Nov 2026 22:48:27 +0000 Subject: [PATCH 1/2] docs(north-star): write docs/NORTH-STAR.md in English as the governing original MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Chinese governing body (125 lines) is translated line for line: no row added, removed, reordered or regraded; every ladder row keeps its `axis · feature · checklist area · item ids` shape with ids and road step numbers unchanged. The non-governing `## English summary` is retired, since the English text is now the original. Every reader that cites a North Star section by its old title is renamed to the new one (AGENTS.md, the pm-dispatch skill and its references, the ensure-pm-labels.sh comment, the checklist README, CONTRIBUTING.md and two test-file comments). Two lanes/skills.md lines were re-cut in place so the longer English title stays under the 120-byte line cap; no ratcheted file gains a line. Co-Authored-By: Claude Claude-Session: https://claude.ai/code/session_017ihL2g7RyXa8ErM6GAkHyc --- .claude/skills/pm-dispatch/SKILL.md | 2 +- .../references/execution-duties.md | 2 +- .../pm-dispatch/references/filing-gate.md | 6 +- .../pm-dispatch/references/lanes/skills.md | 4 +- .../pm-dispatch/references/lanes/spec.md | 2 +- .../pm-dispatch/references/triage-duties.md | 4 +- AGENTS.md | 2 +- CONTRIBUTING.md | 2 +- docs/NORTH-STAR.md | 303 ++++++++---------- docs/qa/platform-checklist/README.md | 2 +- ...e-security-posture.runtime-surface.test.ts | 6 +- scripts/pm/ensure-pm-labels.sh | 4 +- ...plugin-component-input-deprecation.test.ts | 2 +- 13 files changed, 144 insertions(+), 197 deletions(-) diff --git a/.claude/skills/pm-dispatch/SKILL.md b/.claude/skills/pm-dispatch/SKILL.md index 6838025b776..a73071a6c86 100644 --- a/.claude/skills/pm-dispatch/SKILL.md +++ b/.claude/skills/pm-dispatch/SKILL.md @@ -117,7 +117,7 @@ PM 的工作是循环:选卡 → 认领 → 派发 → 收集 → 复核 → 报 | `pm:epic`(父单或 sub-issue) | 已由 epic PM 保留;其它 PM 永不取;⛔ 永不与 `pm:queue` 同挂 | | `pm:seat` | 座位登记贴:协议载体,不是待分诊的工作 | | `priority:p0` | 插队:同轮立即派发,越过 `batch`、深度等待(`LOCK_DEPTH_HOLD`)与一切并发上限;无槽即暂停低级在飞 dev 腾位(机制 `references/execution-duties.md`);⛔ 不豁免同文件串行与认领协议 | -| `area:*` | 功能轴:每卡恰一个;分诊首触打,与 `domain:*` 同笔;工具卡打它所护的轴;⛔ 不回填存量。四读者:维护者按轴看板;定级继承该轴清单项;父单分组;候选顺序,即「功能点位次」= 父单在「路上的功能点」上的次序;同轴至多一个在飞,除非文件面不相交 | +| `area:*` | 功能轴:每卡恰一个;分诊首触打,与 `domain:*` 同笔;工具卡打它所护的轴;⛔ 不回填存量。四读者:维护者按轴看板;定级继承该轴清单项;父单分组;候选顺序,即「功能点位次」= 父单在「Features on the road」上的次序;同轴至多一个在飞,除非文件面不相交 | | open PR 引用该单 | 已实现,复核中 | | merged PR 带 `Fixes #n` | 完成(GitHub 关单) | diff --git a/.claude/skills/pm-dispatch/references/execution-duties.md b/.claude/skills/pm-dispatch/references/execution-duties.md index b203241f809..c40ee979ac3 100644 --- a/.claude/skills/pm-dispatch/references/execution-duties.md +++ b/.claude/skills/pm-dispatch/references/execution-duties.md @@ -46,7 +46,7 @@ - 分诊预见的后续工作是一张卡,触发条件落地时立卡;⛔ 分诊一句话永不授权无卡编辑。 - 阻塞项无主 ⇒ 被挡席认领做掉,不限大小;在该卡走完整认领、尊重其热文件串行队。 - 阻塞项在飞 ⇒ 等:`pm:blocking` 在其车道排最前、等待者写该卡;p0/p1 优先级沿链传递。 -- 取卡前置 = `docs/NORTH-STAR.md`「优先级」第 3 条:本车道队列开放 P0/P1 每次取卡现读。 +- 取卡前置 = `docs/NORTH-STAR.md`「Priority」第 3 条:本车道队列开放 P0/P1 每次取卡现读。 - 开放 = 未派发(无 `pm:dispatched`、无 assignee);在飞的 P0/P1 不挡任何候选,只余取卡全序。 - 每轮每次唤醒首读本车道开着的 `priority:p0`,无人认领即同轮认领派发,⛔ 不等下轮。 - 取卡全序:维护者直派插队卡(出处三件)> 契约面卡(判据见 `references/lanes/spec.md`)> 标签序。 diff --git a/.claude/skills/pm-dispatch/references/filing-gate.md b/.claude/skills/pm-dispatch/references/filing-gate.md index c6938e36fca..7170d9b819b 100644 --- a/.claude/skills/pm-dispatch/references/filing-gate.md +++ b/.claude/skills/pm-dispatch/references/filing-gate.md @@ -22,7 +22,7 @@ - UI 卡写明所需通用块或 spec 契约门;要产品命名 widget/dialog/hook/命名空间的卡退回重立。 - POST 前正文答四件:类别、业务理由、动手的读者(哪席哪步)、查重查询与命中数(含已关)。 - 业务理由:谁受益、什么场景、不做会怎样;③ 以原话代,④ 承父单;分诊 ⛔ 不代写。 -- 清楚且合北极星方向 ⇒ 照常定级入队;与「做出来的是什么」不符或无受益者 = 站不住。 +- 清楚且合北极星方向 ⇒ 照常定级入队;与「What gets built」不符或无受益者 = 站不住。 - 缺失或站不住 ⇒ `Triage: returned` 退回立卡人,留 `finding`,改后再读;⛔ 不代写不关卡。 - 涉及产品取舍或方向不明 ⇒ `needs-user-decision` 入箱,总监席呈批;⛔ 不替维护者判需求。 - 批量立卡(一次 ≥10 张):审计评论带 `Batch-of:` 行,总监席每源抽 ≤5 张呈维护者过目。 @@ -34,7 +34,7 @@ - 分诊席的存量清理仍走维护者确认的十张一组、只备下一组,⛔ 不因本门改批量。 - 读到 `User` ⇒ 记座位贴、本 fire ⛔ 不立新卡;认领仍靠 assignee,署名仍是文本的 session ID。 -## 定级判据(北极星「优先级」的执行说明) +## 定级判据(北极星「Priority」的执行说明) - 协议类:修复改 spec 接受/声明面(含 ADR-0087 转换窗)或 `/meta` 读存删门的收答,宽窄皆算。 - REST/数据门收窄亦算;措辞、文档、账本、CLI 旗、lint/verify 导出、门不变的服务行为不算。 @@ -46,7 +46,7 @@ - ② 项的标题/场景断言该能力而 steps 到不了那条路径 ⇒ 补步骤并继承该项档 ⛔ 不降 p3。 - ③ 无项断言该能力 ⇒ 缺项补账本、北极星第 2 条 p3;②最常见,`area:*` 继承后成规模。 - 假绿另有条款:绿线被读作「已核对」而实际没核对 ⇒ 一次人眼捕获即一次实测代价。 -- 「仪器为车队服务」的四种答案 ⛔ 不压成两条;假红的标准代价形态是席位顺从它。 +- 「Instruments serve the fleet」的四种答案 ⛔ 不压成两条;假红的标准代价形态是席位顺从它。 - 沿链继承只给上界,界内哪格由失效形态定:墙齐平,税降一格;可重入队的 PR 是税。 - 可达面定上界:`security` 标签不抬级;仅最高权限可达且无现用者至多 p3,可记录不修。 - 北极星第 4 条只认出货面(`skills/**`、产品文档),⛔ 不含 `.claude/**` 内部协议。 diff --git a/.claude/skills/pm-dispatch/references/lanes/skills.md b/.claude/skills/pm-dispatch/references/lanes/skills.md index 0e5e029f41a..cb0a5fd90bb 100644 --- a/.claude/skills/pm-dispatch/references/lanes/skills.md +++ b/.claude/skills/pm-dispatch/references/lanes/skills.md @@ -19,8 +19,8 @@ - 额度耗尽豁免的地板是默认判断档,⛔ 不再往下。 - 棘轮逐行付账,⛔ re-wrap 筹行;砍点逐条核幸存,被砍内容若在别处无家,砍掉就是丢规则。 - 首触定级每轮;决策形状 ⇒ 决策箱带四棱块,⛔ 永不自裁。 -- 本车道 finding 归分诊首触,自分诊见 `triage-duties.md`;可附证据与「仪器为车队服务」答案。 -- 「仪器为车队服务」答不出的 finding ⇒ 席位建议 p3 或不做,⛔ 不自入队;定级归分诊。 +- finding 归分诊首触,自分诊见 `triage-duties.md`;可附证据与「Instruments serve the fleet」答案。 +- 「Instruments serve the fleet」答不出的 finding ⇒ 建议 p3 或不做,⛔ 不自入队;定级归分诊。 - 内部指令面中文,机器判据恒英文;认领前重读全线程;标签写 read-modify-write 加回读。 - QA 波次由维护者手动触发,⛔ 不自启。 diff --git a/.claude/skills/pm-dispatch/references/lanes/spec.md b/.claude/skills/pm-dispatch/references/lanes/spec.md index 2f37d6c2e1c..14a9edc178a 100644 --- a/.claude/skills/pm-dispatch/references/lanes/spec.md +++ b/.claude/skills/pm-dispatch/references/lanes/spec.md @@ -20,7 +20,7 @@ - 放宽接受集或扩大公开面的卡,不论多小,即条款②;收窄仍是契约面,不触条款②。 - 收窄不触发条款②,但按 `yes` 申报恒不是错误;⛔ 个案裁决不改本行。 - 机器面改围契约的仪器,与辅助面不交,⛔ 不碰 `packages/spec/src/**/*.zod.ts` 与 strictness 台账。 -- 机器面卡只按北极星「仪器为车队服务」的那一问评级。 +- 机器面卡只按北极星「Instruments serve the fleet」的那一问评级。 - 改元数据格式或接受面的照旧归本席;`/meta` 路由本体在 `packages/rest` 归 `domain:server`。 - 拿不准 FLAG 回分诊,⛔ 不自设判据;档位随面走,表在 SKILL.md 模型分档,⛔ 不另抄。 diff --git a/.claude/skills/pm-dispatch/references/triage-duties.md b/.claude/skills/pm-dispatch/references/triage-duties.md index ebbb11e1d17..81ef82f5c70 100644 --- a/.claude/skills/pm-dispatch/references/triage-duties.md +++ b/.claude/skills/pm-dispatch/references/triage-duties.md @@ -55,8 +55,8 @@ - 停摆指令判据必须比其它分类更硬(双读取),事后证伪同处公开作废。 - `type`(Bug/Feature/Task)立单者可预填、分诊校正;新卡即时打,存量卡 ⛔ 不回填、下次碰到补。 - 判据:违背已声明契约 ⇒ `Bug`,扩大接受集/公开面越出已声明 ⇒ `Feature`,其余 ⇒ `Task`。 -- 定级按北极星「优先级」1–3 条;首行 `Path: <定义项> | <清单项 id/缺项> | P<路步> | none`。 -- 定义项取北极星「做出来的是什么」或仪器卡的车队决定;无则关;`none` 非分诊缺口。 +- 定级按北极星「Priority」1–3 条;首行 `Path: <定义项> | <清单项 id/缺项> | P<路步> | none`。 +- 定义项取北极星「What gets built」或仪器卡的车队决定;无则关;`none` 非分诊缺口。 - 「无则关」= 首触即关 not_planned,带理由与入队三门,⛔ 不定 p3、不 hold;下行同此。 - 所入车道队列 P0/P1 开着(= 未派发,在飞不算)时,三门皆无的 p2/p3 `tooling` 卡同样关。 - 路由属分诊技术判断,⛔ 不升级哪个仓的问题;父单永不派发,`pm:epic` 卡 `pm:retriage` 即答。 diff --git a/AGENTS.md b/AGENTS.md index 5c74d236103..1f9239d274b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -203,7 +203,7 @@ See `ui/AGENTS.md` for the app-id / localStorage / auth gotchas. `packages/spec/src/{domain}/`. Environment-overlay opt-in lives only in `allowEnvironmentOverlay` on `DEFAULT_METADATA_TYPE_REGISTRY` — no parallel whitelists. See ADR-0005, amended by ADR-0131 C5. 8. **North Star alignment.** Read `docs/NORTH-STAR.md` before structural changes. If a change doesn't advance a row of - its 路上的功能点 ladder, graded by its 优先级 — it probably shouldn't ship. + its *Features on the road* ladder, graded by its *Priority* — it probably shouldn't ship. 9. **`OS_` env-var prefix + structure.** All ObjectStack-owned env vars MUST start with `OS_`, then follow **`OS_{DOMAIN}_{FEATURE}[_QUALIFIER]`** where `DOMAIN` is the subsystem (`AUTH`, `SEARCH`, `CORS`, `CLOUD`, `DATABASE`, `CLUSTER`, `MCP`, `SSO`, …) so related vars group together (cf. `OS_AUTH_*`, `OS_CORS_*`). Pick the diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 83bd90deb8f..756b271d389 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -113,7 +113,7 @@ Other examples: `pnpm dev:crm`, `pnpm dev:todo`. Docs site: `pnpm docs:dev`. [issue tracker](https://github.com/objectstack-ai/objectstack/issues), or open one that describes the bug or the proposal before you write code. [docs/NORTH-STAR.md](./docs/NORTH-STAR.md), the project's one North Star, shows where the project is going - and what comes first; an English summary closes it. + and what comes first. 2. **Branch off an up-to-date `main`, one branch and one pull request per issue**, with the issue number in the branch name: diff --git a/docs/NORTH-STAR.md b/docs/NORTH-STAR.md index 931965b4eac..b36e9168ab3 100644 --- a/docs/NORTH-STAR.md +++ b/docs/NORTH-STAR.md @@ -1,178 +1,125 @@ -# ObjectStack 北极星 - -**我们是什么**:本体即软件——一个可执行的业务本体(对象与字段、关系、动作、权限、流程、Agent 与工具定义),AI 写、运行时跑、人与 Agent 用、你拥有;创业阶段。视图、仪表盘、应用、翻译是本体的投影,是今天人用它、看它、验它的面。 - -**给谁**:第三方开发者,AI 代理为主、人验收——AI 进入我们的元数据协议写应用,人看结果、拍板。应用的终端用户是企业里的业务人员,他们通过 Agent 和界面使用应用。 - -**做出来的是什么**:**AI 原生的企业管理应用**——业务对象与记录、看数据的视图、能用的表单、真挡得住的权限、审批与自动化、经营报表、登录与身份、可对外的 API、文件、客户的语言,以及不写代码在运行中改应用。AI 原生的意思:应用自带一个能替用户操作它的 Agent——本仓(社区版)通过 MCP 把对象与动作暴露出去,用户接入自己的 Agent;企业版把 Agent 内置在用户界面里,那一半住 cloud 仓。缺任何一样就不是这个应用。这一行是定义,不是清单;每一项做到什么、怎么验证,在 `docs/qa/platform-checklist/`。参考实现 hotcrm。两类用户:今天的业务人员经界面、验收者经控制台;明天的 Agent 经 MCP。路的每一步都要对两类用户成立。 - -**什么算做好**:一个建在协议上的应用,过了验证才算做好——它的元数据对应的清单项在一次 run 里通过,`objectstack verify` 在它上面是绿的。没过验证的交付不算 done。 - -**唯一的度量,那条路**:一个新的 AI 开发者(人在旁验收)从 `npm create objectstack` 出发:写元数据 → 本地跑起来、看到 → 验证响亮拒绝错的、放行对的 → 发布并装进一个环境 → 接一个 Agent(社区版走 MCP),让它在应用里完成一次真实业务操作 → 按客户一句话需求迭代一次。每周真走一遍,结果落一张 run record。第一个断掉的步骤就是当前的 P0;跑得通但结果错的是 P2。四个承诺各由一步兑现:① AI 可写 · ②③ 可执行 · ④ 你拥有 · ⑤ Agent 可操作 · ⑥ 是闭环。 - -**路上的功能点**:平台要做出来的功能点,一行一个,按那条路的步骤排;自上而下就是顺序 —— 这张表就是路线图,改它即改优先级。每行 `轴 · 功能点(业务语言) · 清单区 · 项 id`,一个功能点从协议到运行时到前端是一整条;`docs/qa/platform-checklist/` 里的每一项都恰好属于这里的一行(未写的项标「清单项待写」)。id 不带前缀时属于它前面那个清单区,跨区的写全名。 - -**① 出发:`npm create objectstack` 起项目,写元数据** - -- devpath · 一条命令起一个项目:脚手架、装好、验证通过、控制台首屏画得出来 · cli · scaffold-first-run, scaffold-console-first-paint -- devpath · 构建是作者的第一道关:错误带位置,产物与统计出得来 · cli · build-own-contract -- devpath · 写进元数据的代码片段有边界:钩子与动作体拒绝越界写法 · cli · hook-body-extraction-gates -- studio · 不写代码建对象、字段、列表、表单与记录页 · studio-authoring · object-designer-roundtrip, view-authoring-live, record-page-roundtrip -- studio · 自定义页面:块组合、页面变量与页面级动作、三档源码 · studio-authoring · custom-page-render-and-blocks, page-variables-and-actions, custom-page-source-tiers -- studio · 先草稿后发布:发布是原子的,冲突与非法草稿当场被拒 · studio-authoring · draft-publish-lifecycle, authoring-validation-not-persisted -- studio · Studio 的判定与边界:表达式与引擎一致、权限矩阵编得动、注册表决定什么能在运行中改 · studio-authoring · expression-editors, permission-matrix-editor-ux, org-override-registry-gate -- studio · 管理员在界面里写 Markdown 文档并加到菜单(含 book),按受众发布成门户 · studio-authoring + platform-core · doc-on-app-menu, platform-core.docs-audience-gate, platform-core.docs-portal-render - -**② 本地跑起来、看到 —— 终端用户在应用里用到的能力,都在这一步第一次被需要** - -- devpath · 一条命令把应用跑起来:健康与就绪都通、数据库选择诚实、端口与陈旧都说出来 · cli + platform-core · dev-boot-contract, platform-core.boot-health, platform-core.runtime-config-boot-read -- devpath · 种子数据原样落库,重放不多不少 · platform-core · seed-integrity, seed-mode-matrix -- devpath · 登得进去,外壳记得住:导航、自带应用、收藏与最近、主题、快捷键、返回键 · platform-core · console-login, nav-surfaces-render, builtin-apps-nav-render, shell-nav-personalization, theme-mode-persistence, keyboard-shortcut-surface, url-overlay-contract, home-admin-cluster-links, console-installability-indicators, app-management-toggle -- devpath · 平台设置在界面里改:改完真的生效、留痕、密钥只存句柄 · platform-core · settings-hub-roundtrip -- devpath · 遥测与生命周期数据按保留期回收,声明了归档的对象绝不热删 · platform-core · lifecycle-retention-sweep -- devpath · 元数据注册表对外可读,只有可写的包改得动 · platform-core · metadata-registry-serving, metadata-authoring-roundtrip -- records · 一条记录建出来、看见、改掉、删掉,也能照着再建一条 · records-forms · crud-roundtrip, record-clone-contract -- records · 每种字段都渲染得出、收得下、存得住,错的当场拒 · records-forms · field-type-matrix, field-type-constraints, field-unique-enforcement, encrypted-field-behavior -- records · 列表能干活:筛选、搜索、排序、分页、保存视图、行内编辑、导出、批量 · records-forms · list-view-capabilities, view-type-gallery, adhoc-filter-sort-builder, grid-personalization, saved-view-management, bulk-select-all-matching -- records · 看板、日历、甘特是能拖的,不是图片 · records-forms · kanban-drag-persistence, calendar-interactions, gantt-interactions -- records · 表单能用:布局、脏数据守卫、联动显示与必填、级联选项 · records-forms · form-view-gallery, form-dirty-guard, conditional-rules-header, conditional-rules-grid, cascading-options, cascading-multilevel-and-clear, field-group-visible-when -- records · 主从一起存、相关列表在服务端分页、查找框里顺手新建 · records-forms · master-detail-atomic-save, related-list-server-pagination, lookup-picker-create-new -- records · 写入规则在服务端兑现,撞车响亮、后悔得了、改过什么看得见 · records-forms · validation-rule-type-matrix, object-hook-lifecycle, delete-behavior-matrix, concurrent-edit-conflict, record-edit-undo, field-history-tracking -- records · 记录上的动作与协作:按钮在声明的位置、参数契约在派发时兑现、讨论与 @ 提醒 · records-forms · action-location-matrix, action-param-widgets, upload-guard-blocks-confirm, record-discussion-mentions -- records · 搜得到:跨字段、字段限定、权限一致、拼音、即时新鲜;全局搜索与命令面板同一条路 · search · cross-field-object-search, field-scoped-narrowing, rls-both-personas, pinyin-flag-both-sides, freshness-and-empty, console-global-search, command-palette-navigation -- records · 共享选项集:多个对象复用同一份选项 · records-forms · picklist-shared-across-objects -- access · 行级与字段级权限两边都对:受限成员只看自己的,该只读的只读、该看不见的不回给前端 · access-security · rls-both-sides, scope-depth-asymmetry, fls-mask-and-strip -- access · 增删改查逐格兑现,改完权限立刻换脸,自查接口与服务端一致 · access-security · crud-permission-matrix, permission-matrix-edit-loop, me-permissions-aggregation-parity -- access · 写入路径挡得住:只读剥离、伪造与转移 owner 被拒、默认可见度只能收紧 · access-security · write-path-guards, owd-save-gate -- access · 共享:默认基线、规则放宽、单条手工共享、建议的绑定 · access-security · owd-sharing-matrix, sharing-rules-widen, record-share-grant-revoke, sharing-rule-authoring-ui, suggested-binding-loop -- access · 匿名进不来:每个 API 家族统一拒,且先于任何资源解析;没有活跃组织也是合法状态 · access-security · anonymous-deny-surfaces, no-active-org-session-semantics -- access · 对外开的小门:公开表单与分享链接,能收回、不泄露 · access-security · public-form-intake, share-link-capability-tokens, share-link-landing-page -- access · 说得清也查得到:逐层归因的访问解释、审计浏览、记录查看留痕、平台管理员身份本身挡得住 · access-security · record-access-explain, audit-log-browser, record-view-read-audit, platform-owner-email-anchor -- identity · 登录方式按配置开关,广告出来的就是真能用的 · identity-auth · auth-method-matrix, sso-enforced-first-paint, phone-signin-surfaces -- identity · 第一次装好就有主人:零用户首跑、注册闸门、邮箱验证 · identity-auth · first-run-owner-bootstrap, self-signup-gate, email-verification-loop -- identity · 自己回得来、自己改得动:忘了密码、改资料、看得见也收得回会话 · identity-auth · self-service-password-reset, self-service-profile-password, session-list-revoke -- identity · 两步验证:开启、验证、备份码、关闭 · identity-auth · two-factor-enrollment-reveal, two-factor-verify-to-activate, two-factor-backup-codes, two-factor-disable-lifecycle -- identity · 组织、团队与业务单元,以及管理员的用户运维 · identity-auth · org-membership-team-management, teams-bu-membership, invitation-scope-gates, workspace-org-switch, admin-lifecycle-operations, identity-import-wizard -- identity · 对外身份:OAuth 授权与社交账号绑定 · identity-auth · oauth-app-consent-loop, linked-accounts-social -- workflow · 审批走得完:会签、法定人数、动态审批人、超时升级、请假代理 · approvals · per-group-signoff, quorum-m-of-n, dynamic-approver-routing, sla-escalation, ooo-delegation-reroute, approver-resolution-matrix -- workflow · 审批在界面里做:收件箱、记录页按钮、键盘流、待办计数、通知直达 · approvals · inbox-metadata-actions, viewer-gating-submitter-side, record-page-decisions, inbox-keyboard-flow, pending-count-surfaces, account-app-entry, setup-nav-entry, notification-deep-link -- workflow · 审批的每个动作都由服务端状态机兜底,邮件一键也是同一条路 · approvals · decision-action-matrix, decision-only-via-service, status-mirror-field, email-action-token-door -- workflow · 流程跑得起来:节点类型、触发类型、运行树与日志 · automation · flow-node-type-matrix, trigger-type-matrix, flow-run-step-nesting, flow-runs-page-test-trigger, trigger-status-contract -- workflow · 流程的出错、暂停与定时:try/catch、屏幕流、冷重启接着跑、汇总与时间触发、开关即刹车 · automation · flow-error-handling, screen-flow-roundtrip, durable-suspend-restart, rollup-summary-filter, time-relative-trigger, flow-toggle-kill-switch -- reports · 图表画得出来、类型齐、空数据体面、写错的键响亮;钻得下去、全局筛选重新取数 · dashboards · chart-first-paint, chart-type-matrix, empty-null-bucket-boundaries, strict-widget-rejects-stray-keys, drill-through-range, global-filters-rescope -- reports · 报表自己建、自己存、只归自己,还能按时自己发出去 · dashboards · dataset-report-authoring, saved-report-ownership, report-schedule-dispatch-delivery -- reports · 经营数字对得上:系统总览与分析立方体 · dashboards · system-overview-live-counts, cube-query -- files · 传得上、下得来,权限跟着父记录走 · attachments-storage · presigned-upload-roundtrip, download-authz-both-sides, read-inherits-parent-rls, attach-requires-parent-edit -- files · 文件的一生与表单里的文件格:提交、墓碑、回收、续传,大小与类型服务端再验一次 · attachments-storage · sys-file-status-pipeline, orphan-tombstone-reap, upload-session-abort, inline-grid-receipt-cells, field-accept-maxsize-server-enforced -- i18n · 整个应用说客户的语言,Studio 跟着切,通知也落到对的语言 · i18n · surface-matrix, studio-follows-app-locale, notification-localized-and-clears -- api · 查询契约:算子、参数、聚合、日期窗口都有已知答案 · api-backend · query-contract-matrix, aggregate-contract-matrix, date-range-preset-matrix, filter-comparand-conformance -- api · 批量与写入门逐行有结果;错误信封与路由台账:码是登记过的,挂出来的就是真在跑的 · api-backend · bulk-write-contract, batch-transactional-discovery, error-envelope-ledger, route-ledger-live-parity -- api · 自己声明的 API 端点挂成真 URL,开发者控制台里当场试得通 · api-backend · declarative-endpoint-execution, api-console-discovery-execute -- api · REST 面的构造契约:开关决定挂什么、哪些动词准过,计时只对管理员开 · api-backend · rest-crud-config-contract, rest-batch-config-contract, rest-metadata-config-contract, rest-route-generation-tombstones, api-methods-verb-gate, server-timing-admin-gated -- api · 公式引擎:标准库函数逐个给出已知答案,写错的表达式在构建时就被挡下 · api-backend · formula-stdlib-matrix, formula-gates -- api · 连上外部系统:连接器声明式落地、坏了只降级一个、鉴权与命令白名单、流程里调得到 · integration-system + automation · connector-declarative-boot, connector-degraded-recovery, connector-stdio-default-deny, connector-spec-path-no-escape, connector-descriptor-audit, connector-auth-kind-application, flow-connector-picker, automation.connector-dispatch-matrix -- api · 外部数据源接进来当自己的对象用,密钥写不进也读不出 · integration-system + cli · external-datasource-federated-read, external-schema-introspection, external-schema-drift-gate, external-schema-browser-ui, datasource-admin-lifecycle, datasource-credential-refusal-matrix, cli.datasource-introspect-codegen -- api · 往外发、往里收:webhook、定时任务、邮件模板、收件箱投递与订阅偏好、铃铛已读 · integration-system + platform-core · webhook-lifecycle, job-scheduled-run, email-template-render, notify-inbox-delivery, notification-preference-suppression, platform-core.notification-center - -**③ 验证:响亮拒绝错的,放行对的** - -- devpath · `objectstack verify` 的判词是封闭的,失败才非零退出;质量套件跑在真应用上 · cli · verify-verdict-exit-mapping, qa-suite-execution -- devpath · 体检与弃用扫描:每项都有归属,说得出处方 · cli · doctor-health-report, doctor-deprecation-scan -- devpath · lint 的严重度是封闭的,只有错误才拦;命令用错了要响亮 · cli · lint-severity-exit-contract, flag-command-error-ux -- api · 写错的元数据在作者的门口就被拒,并给处方 · api-backend · enforce-or-remove-authoring-gates, retired-def-refusal -- i18n · 翻译键写错了两个门都拒,构建门禁能变红 · i18n · strict-translation-key-rejection, build-gates-hold -- studio · 存量元数据的体检:逐条报出不合规与位置 · studio-authoring · metadata-diagnostics-sweep - -**④ 发布并装进一个环境** - -- devpath · 打成插件:清单在打包边界就被强制 · cli · plugin-manifest-build-contract -- devpath · 装进来:兼容性、命名空间、启停与卸载,REST 侧同一套生命周期 · platform-core + api-backend · manifest-install-contract, package-lifecycle-enable-disable, api-backend.package-rest-lifecycle -- devpath · 从市场装:有没有控制面都装得上,界面不说谎 · platform-core · marketplace-install-local-lifecycle, marketplace-console-honesty -- devpath · 迁移:先看计划再动手,中断了说得出下一步,老写法给得出改法 · cli + platform-core · migrate-plan-apply-json, migrate-meta-codemod, migrate-duplicates-inventory, platform-core.interrupted-migration-boot-report -- devpath · 随包发来的对象只能扩不能改,启停逐条记在激活台账上 · platform-core + access-security · packaged-object-extend-only, activation-ledger-registration-home, activation-ledger-row-contract, access-security.activation-write-operator-gate -- workflow · 随包发的流程与动作:停用要持久、被依赖时拒绝、可克隆、两道门一样严 · automation + api-backend + access-security · packaged-flow-disable-durable, packaged-flow-subflow-disable-refusal, packaged-flow-clone-contract, setup-packaged-automation-board, api-backend.packaged-action-disabled-dispatch, api-backend.action-activation-door-contract, access-security.packaged-flow-write-door-parity -- access · 装进来的包带着它声明的能力与权限集,只读的包锁住 Studio · access-security + studio-authoring · capability-declaration-lifecycle, packaged-permission-set-lifecycle, readonly-package-locks-studio, studio-authoring.packaged-automation-studio-lock -- studio · 随包发来的视图与仪表盘,是可以直接改的那一类 · studio-authoring · packaged-display-class-direct-edit -- devpath · 你拥有:定义在你的仓库里可 diff,整个本体可导出、可在没有我们的情况下自托管跑起来 · platform-core + cli · ontology-export-roundtrip, artifact-reproducible-build, standalone-boot-no-cloud(清单项待写) - -**⑤ 接一个 Agent(社区版走 MCP),让它完成一次真实业务操作** - -- ai · agent / tool / skill 元数据写得进、列得出,退役键给处方 · ai · agent-tool-skill-metadata-roundtrip -- ai · MCP 面按文档开关:HTTP 与 stdio 两条路都失败向关 · ai · mcp-http-surface, mcp-stdio-fail-closed -- ai · Agent 能做的就是应用真能做的:动作先开口子,表达式当场校验 · ai · mcp-run-action-exposure-gate, mcp-validate-expression -- ai · 技能说明书投到 MCP 的提示上 · ai · skill-instructions-mcp-prompts -- ai · 社区版没有的就诚实说没有,界面也不摆空架子 · ai · open-edition-honest-degradation, console-ai-surface-gating -- identity · 给 Agent 一把个人密钥:只显示一次,能撤也能恢复 · identity-auth · api-key-ui-lifecycle - -**⑥ 按客户一句话需求迭代一次** - -- studio · 首跑闭环:建包 → 建对象 → 记录 → 应用 → 发布 → 终端用户,零代码零重启 · studio-authoring · first-run-loop -- records · 把客户的存量数据搬进来:编码、映射、转换、撤销与取消 · records-forms · import-wizard-encoding-and-hints, named-import-mapping, import-job-undo-cancel, import-transform-matrix -- devpath · 迭代带来的结构变化:dev 启动只自愈安全的那部分,生产不自作主张 · cli · dev-automigrate-policy - -**优先级**: -1. 安全与数据完整性永远最高,不等路。 -2. 路断了、或清单上的能力断了 ⇒ P0/P1;能跑但出错 ⇒ P2;不在路上、不在清单上 ⇒ p3 或不做。定级读「路上的功能点」:改那张表即改优先级,⛔ 不逐卡改档。 -3. 本车道队列还有开放的 P0/P1 时,该车道不派 p2/p3 的工具卡、契约卫生卡;解锁产品 P0/P1 的仪器卡沿链继承其优先级。 -4. 因为写的是 AI、用的也是 AI:本体既要 AI 能写——错的必须被响亮拒绝并给处方,永不静默落库;也要人与 Agent 能用——声明了的对象、动作、agent / tool / skill 元数据在运行时兑现,MCP 面暴露的就是应用真能做的,Agent 越权时被权限挡住并留痕。人用的那一半也有标准:作者不写一行界面代码,得到的界面要像设计师经手过——同一套设计系统、同一种版式;看着不对与渲染不出同样是缺陷,在「看到」那一步就被拒。写给 AI 的文档与 skills 说错一句,等于产品缺陷。 - -**阶段姿态**:速度优先于兼容。用的人少:退役立即生效,无过渡窗口、无别名双拼;兼容层、迁移窗口一类的工作默认 p3;声明了但不兑现的键按发布批量退役,不一键一卡。 - -**仪器为车队服务**:改 PM 协议、门禁、棘轮、技能的卡,以「它落地后车队的哪个决定或动作会不一样」评级——说得出(一次本来会派错的派发、一次落不了的落地、一次放过假货的复核、一个卡住的席位),就按上面的规则定级,与产品卡同场竞争;说不出,就不做。 - -**现在不做**:云服务的旅程(注册、控制面、托管)另有自己的清单;企业版内置 Agent 属 cloud 仓,不在本仓的路与清单里;计费未建。 - -**账本**:能力与验证的账本是 `docs/qa/platform-checklist/`,本页不复制它。本页不带任何数字;数字从命令来。 - ---- - -## English summary - -A reading aid for readers without Chinese. The Chinese text above is the original and is what governs; this summary -restates its opening, its one measure and how to read its ladder, and adds nothing to them. - -**The four opening questions** - -- **What we are** (我们是什么) — the ontology is the software: an executable business ontology (objects and fields, - relationships, actions, permissions, flows, agent and tool definitions) that AI writes, the runtime runs, people and - agents use, and you own; startup stage. Views, dashboards, apps and translations are projections of the ontology — - the surfaces through which people use, see and verify it today. -- **Who it is for** (给谁) — third-party developers, AI agents first with a human accepting: the AI writes applications - in our metadata protocol, the human looks at the result and decides. The applications' end users are business staff - in companies, who use them through agents and the UI. -- **What gets built** (做出来的是什么) — **AI-native enterprise management applications**: business objects and records, - views to see the data, forms that work, permissions that really hold, approvals and automation, business reports, - sign-in and identity, an API others can call, files, the customer's language, and changing the application while it - runs without writing code. AI-native means the application carries an agent that can operate it for the user: this - repository (the community edition) exposes objects and actions over MCP and users connect their own agent; the - enterprise edition builds the agent into the UI, and that half lives in the cloud repository. Missing any one of - these, it is not this application. The line is a definition, not a checklist — what each item must do and how it is - verified is in `docs/qa/platform-checklist/`. Reference implementation: hotcrm. Two kinds of user: today business - staff through the UI and acceptors through the console, tomorrow agents through MCP; every step of the road must hold - for both. -- **What counts as done** (什么算做好) — an application built on the protocol is done only once it passes verification: - the checklist items its metadata maps to pass in one run, and `objectstack verify` is green on it. A delivery that - has not passed verification is not done. - -**The one measure: the road** (唯一的度量,那条路) - -A new AI developer, a human accepting alongside, starts from `npm create objectstack`: ① write metadata → ② run it -locally and see it → ③ verification loudly rejects what is wrong and lets through what is right → ④ publish and -install into an environment → ⑤ connect an agent (MCP in the community edition) and have it complete one real business -operation in the application → ⑥ iterate once on a one-sentence customer request. Walk it for real every week and -record the result as a run record. The first step that breaks is the current P0; a step that runs but gives a wrong -result is P2. Each promise is kept by a step: ① AI can write it · ②③ it executes · ④ you own it · ⑤ agents can operate -it · ⑥ it closes the loop. - -**How to read the ladder** (路上的功能点) - -- The ladder lists the features the platform has to deliver, one per line, under the road's steps ① to ⑥; top to - bottom is the order. The table is the roadmap: editing it changes priority. -- Each row reads `axis · feature (in business language) · checklist area · item ids`, and one feature is a whole strip - from protocol through runtime to the frontend. Every item in `docs/qa/platform-checklist/` belongs to exactly one - row; a feature whose items are not written yet is marked 「清单项待写」 (checklist item to be written). An id without a - prefix belongs to the checklist area before it; an id from another area is written in full. -- Grading reads the ladder (优先级): safety and data integrity always come first and do not wait for the road; a broken - road step or a broken checklist capability is P0/P1, one that runs but is wrong is P2, and work on neither the road - nor the checklist is p3 or not done. Change the table to change priority — ⛔ never re-grade card by card. The rest - of 优先级 and the paragraphs after it (阶段姿态, 仪器为车队服务, 现在不做, 账本) are read in the Chinese text above. +# ObjectStack North Star + +**What we are**: the ontology is the software — an executable business ontology (objects and fields, relationships, actions, permissions, flows, agent and tool definitions) that AI writes, the runtime runs, people and agents use, and you own; startup stage. Views, dashboards, apps and translations are projections of the ontology — the surfaces through which people use it, see it and verify it today. + +**Who it is for**: third-party developers, AI agents first with a human accepting — the AI enters our metadata protocol and writes applications, the human looks at the result and decides. The applications' end users are the business staff in companies, who use the applications through agents and the UI. + +**What gets built**: **AI-native enterprise management applications** — business objects and records, views to see the data, forms that work, permissions that really hold, approvals and automation, business reports, sign-in and identity, an API others can call, files, the customer's language, and changing the application while it runs without writing code. AI-native means: the application carries an agent that can operate it on the user's behalf — this repository (the community edition) exposes objects and actions over MCP and users connect their own agent; the enterprise edition builds the agent into the user interface, and that half lives in the cloud repository. Missing any one of these, it is not this application. This line is a definition, not a checklist; what each item must do and how it is verified is in `docs/qa/platform-checklist/`. Reference implementation: hotcrm. Two kinds of user: today, business staff through the UI and acceptors through the console; tomorrow, agents through MCP. Every step of the road must hold for both kinds of user. + +**What counts as done**: an application built on the protocol is done only once it has passed verification — the checklist items its metadata maps to pass in one run, and `objectstack verify` is green on it. A delivery that has not passed verification does not count as done. + +**The one measure: the road**: a new AI developer (a human accepting alongside) starts from `npm create objectstack`: write metadata → run it locally and see it → verification loudly rejects what is wrong and lets through what is right → publish and install into an environment → connect an agent (MCP in the community edition) and have it complete one real business operation in the application → iterate once on a one-sentence customer request. Walk it for real every week, and the result lands as a run record. The first step that breaks is the current P0; one that runs through but gives a wrong result is P2. The four promises are each kept by a step: ① AI can write it · ②③ it executes · ④ you own it · ⑤ agents can operate it · ⑥ it closes the loop. + +**Features on the road**: the features the platform has to deliver, one per line, arranged by the steps of that road; top to bottom is the order — this table is the roadmap, and editing it is editing priority. Each row reads `axis · feature (in business language) · checklist area · item ids`, and one feature is a whole strip from protocol through runtime to the frontend; every item in `docs/qa/platform-checklist/` belongs to exactly one row here (an item not yet written is marked "checklist item to be written"). An id without a prefix belongs to the checklist area before it; one from another area is written in full. + +**① Set out: start a project with `npm create objectstack`, write metadata** + +- devpath · One command starts a project: scaffolded, installed, verification passes, the console's first screen paints · cli · scaffold-first-run, scaffold-console-first-paint +- devpath · The build is the author's first gate: errors carry a location, artifacts and statistics come out · cli · build-own-contract +- devpath · Code snippets written into metadata have boundaries: hook and action bodies refuse out-of-bounds spellings · cli · hook-body-extraction-gates +- studio · Build objects, fields, lists, forms and record pages without writing code · studio-authoring · object-designer-roundtrip, view-authoring-live, record-page-roundtrip +- studio · Custom pages: block composition, page variables and page-level actions, three source tiers · studio-authoring · custom-page-render-and-blocks, page-variables-and-actions, custom-page-source-tiers +- studio · Draft first, then publish: publishing is atomic, and conflicts and invalid drafts are refused on the spot · studio-authoring · draft-publish-lifecycle, authoring-validation-not-persisted +- studio · Studio's judgements and boundaries: expressions agree with the engine, the permission matrix can be edited, the registry decides what can change at runtime · studio-authoring · expression-editors, permission-matrix-editor-ux, org-override-registry-gate +- studio · An administrator writes Markdown documents in the UI and adds them to the menu (books included), published as a portal by audience · studio-authoring + platform-core · doc-on-app-menu, platform-core.docs-audience-gate, platform-core.docs-portal-render + +**② Run it locally and see it — every capability an end user uses in the application is needed for the first time at this step** + +- devpath · One command runs the application: health and readiness both pass, the database choice is honest, port and staleness are both said out loud · cli + platform-core · dev-boot-contract, platform-core.boot-health, platform-core.runtime-config-boot-read +- devpath · Seed data lands in the database as written, and a replay adds nothing and loses nothing · platform-core · seed-integrity, seed-mode-matrix +- devpath · You can sign in, and the shell remembers: navigation, built-in apps, favourites and recents, theme, keyboard shortcuts, the back key · platform-core · console-login, nav-surfaces-render, builtin-apps-nav-render, shell-nav-personalization, theme-mode-persistence, keyboard-shortcut-surface, url-overlay-contract, home-admin-cluster-links, console-installability-indicators, app-management-toggle +- devpath · Platform settings change in the UI: a change really takes effect, leaves a trace, and secrets are stored only as handles · platform-core · settings-hub-roundtrip +- devpath · Telemetry and lifecycle data are reclaimed by retention period, and an object declared as archived is never hot-deleted · platform-core · lifecycle-retention-sweep +- devpath · The metadata registry is readable from outside, and only a writable package can be changed · platform-core · metadata-registry-serving, metadata-authoring-roundtrip +- records · A record is created, seen, changed and deleted, and another can be made from it · records-forms · crud-roundtrip, record-clone-contract +- records · Every field type renders, accepts input and persists, and a wrong value is refused on the spot · records-forms · field-type-matrix, field-type-constraints, field-unique-enforcement, encrypted-field-behavior +- records · Lists get work done: filter, search, sort, paginate, saved views, inline editing, export, bulk · records-forms · list-view-capabilities, view-type-gallery, adhoc-filter-sort-builder, grid-personalization, saved-view-management, bulk-select-all-matching +- records · Kanban, calendar and Gantt can be dragged; they are not pictures · records-forms · kanban-drag-persistence, calendar-interactions, gantt-interactions +- records · Forms work: layout, dirty-data guard, conditional visibility and required rules, cascading options · records-forms · form-view-gallery, form-dirty-guard, conditional-rules-header, conditional-rules-grid, cascading-options, cascading-multilevel-and-clear, field-group-visible-when +- records · Master and detail save together, related lists paginate on the server, and a lookup picker creates a new record in passing · records-forms · master-detail-atomic-save, related-list-server-pagination, lookup-picker-create-new +- records · Write rules are honoured on the server: a collision is loud, an edit can be undone, and what changed is visible · records-forms · validation-rule-type-matrix, object-hook-lifecycle, delete-behavior-matrix, concurrent-edit-conflict, record-edit-undo, field-history-tracking +- records · Actions and collaboration on a record: buttons sit where they are declared, the parameter contract is honoured at dispatch, discussion and @-mentions · records-forms · action-location-matrix, action-param-widgets, upload-guard-blocks-confirm, record-discussion-mentions +- records · Search finds it: across fields, scoped to a field, consistent with permissions, pinyin, fresh at once; global search and the command palette take the same road · search · cross-field-object-search, field-scoped-narrowing, rls-both-personas, pinyin-flag-both-sides, freshness-and-empty, console-global-search, command-palette-navigation +- records · Shared option sets: several objects reuse one set of options · records-forms · picklist-shared-across-objects +- access · Row-level and field-level permissions are right on both sides: a restricted member sees only their own, what should be read-only is read-only, and what should be invisible is not returned to the frontend · access-security · rls-both-sides, scope-depth-asymmetry, fls-mask-and-strip +- access · Create, read, update and delete are honoured cell by cell, a permission change shows at once, and the self-check endpoint agrees with the server · access-security · crud-permission-matrix, permission-matrix-edit-loop, me-permissions-aggregation-parity +- access · The write path holds: read-only fields are stripped, a forged or transferred owner is refused, and default visibility can only be tightened · access-security · write-path-guards, owd-save-gate +- access · Sharing: the default baseline, rules that widen, manual sharing of a single record, suggested bindings · access-security · owd-sharing-matrix, sharing-rules-widen, record-share-grant-revoke, sharing-rule-authoring-ui, suggested-binding-loop +- access · Anonymous cannot get in: every API family refuses uniformly, and before any resource is resolved; having no active organization is also a legal state · access-security · anonymous-deny-surfaces, no-active-org-session-semantics +- access · The small doors opened to the outside: public forms and share links, revocable and leak-free · access-security · public-form-intake, share-link-capability-tokens, share-link-landing-page +- access · Explainable and auditable: access explanations attributed layer by layer, an audit log browser, record views leave a trace, and the platform administrator identity itself holds · access-security · record-access-explain, audit-log-browser, record-view-read-audit, platform-owner-email-anchor +- identity · Sign-in methods switch on and off by configuration, and what is advertised really works · identity-auth · auth-method-matrix, sso-enforced-first-paint, phone-signin-surfaces +- identity · The first install has an owner: zero-user first run, the sign-up gate, email verification · identity-auth · first-run-owner-bootstrap, self-signup-gate, email-verification-loop +- identity · You can get back in and change things yourself: forgotten password, profile changes, sessions you can see and revoke · identity-auth · self-service-password-reset, self-service-profile-password, session-list-revoke +- identity · Two-factor authentication: enable, verify, backup codes, disable · identity-auth · two-factor-enrollment-reveal, two-factor-verify-to-activate, two-factor-backup-codes, two-factor-disable-lifecycle +- identity · Organizations, teams and business units, and the administrator's user operations · identity-auth · org-membership-team-management, teams-bu-membership, invitation-scope-gates, workspace-org-switch, admin-lifecycle-operations, identity-import-wizard +- identity · External identity: OAuth consent and linked social accounts · identity-auth · oauth-app-consent-loop, linked-accounts-social +- workflow · An approval runs to completion: joint sign-off, quorum, dynamic approvers, timeout escalation, out-of-office delegation · approvals · per-group-signoff, quorum-m-of-n, dynamic-approver-routing, sla-escalation, ooo-delegation-reroute, approver-resolution-matrix +- workflow · Approvals are done in the UI: the inbox, record-page buttons, a keyboard flow, pending counts, notifications that deep-link · approvals · inbox-metadata-actions, viewer-gating-submitter-side, record-page-decisions, inbox-keyboard-flow, pending-count-surfaces, account-app-entry, setup-nav-entry, notification-deep-link +- workflow · Every approval action is backed by the server-side state machine, and the one-click email action takes the same road · approvals · decision-action-matrix, decision-only-via-service, status-mirror-field, email-action-token-door +- workflow · Flows run: node types, trigger types, the run tree and logs · automation · flow-node-type-matrix, trigger-type-matrix, flow-run-step-nesting, flow-runs-page-test-trigger, trigger-status-contract +- workflow · Flow errors, pauses and schedules: try/catch, screen flows, resuming after a cold restart, rollups and time-based triggers, the toggle is the brake · automation · flow-error-handling, screen-flow-roundtrip, durable-suspend-restart, rollup-summary-filter, time-relative-trigger, flow-toggle-kill-switch +- reports · Charts paint, every type is there, empty data is handled gracefully, a wrong key is loud; drill-through works and global filters refetch · dashboards · chart-first-paint, chart-type-matrix, empty-null-bucket-boundaries, strict-widget-rejects-stray-keys, drill-through-range, global-filters-rescope +- reports · Reports you build, save and own yourself, and that send themselves on schedule · dashboards · dataset-report-authoring, saved-report-ownership, report-schedule-dispatch-delivery +- reports · The business numbers add up: the system overview and the analytics cube · dashboards · system-overview-live-counts, cube-query +- files · Upload and download work, and permissions follow the parent record · attachments-storage · presigned-upload-roundtrip, download-authz-both-sides, read-inherits-parent-rls, attach-requires-parent-edit +- files · A file's lifetime and the file cell in a form: submit, tombstone, reap, resume; size and type are checked again on the server · attachments-storage · sys-file-status-pipeline, orphan-tombstone-reap, upload-session-abort, inline-grid-receipt-cells, field-accept-maxsize-server-enforced +- i18n · The whole application speaks the customer's language, Studio switches with it, and notifications land in the right language too · i18n · surface-matrix, studio-follows-app-locale, notification-localized-and-clears +- api · The query contract: operators, parameters, aggregates and date windows all have known answers · api-backend · query-contract-matrix, aggregate-contract-matrix, date-range-preset-matrix, filter-comparand-conformance +- api · Bulk and the write door answer row by row; the error envelope and the route ledger: every code is registered, and what is mounted is what really runs · api-backend · bulk-write-contract, batch-transactional-discovery, error-envelope-ledger, route-ledger-live-parity +- api · A self-declared API endpoint mounts as a real URL and can be tried on the spot in the developer console · api-backend · declarative-endpoint-execution, api-console-discovery-execute +- api · The REST surface's construction contract: switches decide what mounts and which verbs pass, timing opens to administrators only · api-backend · rest-crud-config-contract, rest-batch-config-contract, rest-metadata-config-contract, rest-route-generation-tombstones, api-methods-verb-gate, server-timing-admin-gated +- api · The formula engine: every standard-library function gives a known answer, and a wrong expression is stopped at build time · api-backend · formula-stdlib-matrix, formula-gates +- api · Connect to external systems: connectors land declaratively, a broken one degrades alone, auth and command allowlists, callable from a flow · integration-system + automation · connector-declarative-boot, connector-degraded-recovery, connector-stdio-default-deny, connector-spec-path-no-escape, connector-descriptor-audit, connector-auth-kind-application, flow-connector-picker, automation.connector-dispatch-matrix +- api · An external data source plugs in and is used as your own objects; secrets can be neither written in nor read out · integration-system + cli · external-datasource-federated-read, external-schema-introspection, external-schema-drift-gate, external-schema-browser-ui, datasource-admin-lifecycle, datasource-credential-refusal-matrix, cli.datasource-introspect-codegen +- api · Send out, take in: webhooks, scheduled jobs, email templates, inbox delivery and subscription preferences, the bell's read state · integration-system + platform-core · webhook-lifecycle, job-scheduled-run, email-template-render, notify-inbox-delivery, notification-preference-suppression, platform-core.notification-center + +**③ Verify: loudly reject what is wrong, let through what is right** + +- devpath · `objectstack verify`'s verdicts are a closed set, and only a failure exits non-zero; the quality suite runs on a real application · cli · verify-verdict-exit-mapping, qa-suite-execution +- devpath · Health check and deprecation scan: every item has an owner and can state a prescription · cli · doctor-health-report, doctor-deprecation-scan +- devpath · Lint severities are a closed set, and only an error blocks; a misused command is loud · cli · lint-severity-exit-contract, flag-command-error-ux +- api · Wrong metadata is refused at the author's door, with a prescription · api-backend · enforce-or-remove-authoring-gates, retired-def-refusal +- i18n · A wrong translation key is refused at both doors, and the build gate can go red · i18n · strict-translation-key-rejection, build-gates-hold +- studio · A health check of existing metadata: every non-compliance reported with its location · studio-authoring · metadata-diagnostics-sweep + +**④ Publish and install into an environment** + +- devpath · Pack as a plugin: the manifest is enforced at the packaging boundary · cli · plugin-manifest-build-contract +- devpath · Install it: compatibility, namespaces, enable, disable and uninstall, with the same lifecycle on the REST side · platform-core + api-backend · manifest-install-contract, package-lifecycle-enable-disable, api-backend.package-rest-lifecycle +- devpath · Install from the marketplace: it installs with or without a control plane, and the UI does not lie · platform-core · marketplace-install-local-lifecycle, marketplace-console-honesty +- devpath · Migration: see the plan before acting, an interrupted one can say the next step, and an old spelling gets a fix · cli + platform-core · migrate-plan-apply-json, migrate-meta-codemod, migrate-duplicates-inventory, platform-core.interrupted-migration-boot-report +- devpath · A packaged object can be extended but not changed, and every enable and disable is recorded on the activation ledger · platform-core + access-security · packaged-object-extend-only, activation-ledger-registration-home, activation-ledger-row-contract, access-security.activation-write-operator-gate +- workflow · Packaged flows and actions: disabling is durable, refused while depended on, cloneable, and both doors are equally strict · automation + api-backend + access-security · packaged-flow-disable-durable, packaged-flow-subflow-disable-refusal, packaged-flow-clone-contract, setup-packaged-automation-board, api-backend.packaged-action-disabled-dispatch, api-backend.action-activation-door-contract, access-security.packaged-flow-write-door-parity +- access · An installed package carries the capabilities and permission sets it declares, and a read-only package locks Studio · access-security + studio-authoring · capability-declaration-lifecycle, packaged-permission-set-lifecycle, readonly-package-locks-studio, studio-authoring.packaged-automation-studio-lock +- studio · Packaged views and dashboards are the class that can be edited directly · studio-authoring · packaged-display-class-direct-edit +- devpath · You own it: the definitions are diffable in your repository, and the whole ontology can be exported and run self-hosted without us · platform-core + cli · ontology-export-roundtrip, artifact-reproducible-build, standalone-boot-no-cloud (checklist item to be written) + +**⑤ Connect an agent (MCP in the community edition) and have it complete one real business operation** + +- ai · agent / tool / skill metadata can be written and listed, and a retired key gets a prescription · ai · agent-tool-skill-metadata-roundtrip +- ai · The MCP surface switches as documented: both the HTTP and the stdio road fail closed · ai · mcp-http-surface, mcp-stdio-fail-closed +- ai · What an agent can do is what the application really can do: an action is exposed first, an expression is validated on the spot · ai · mcp-run-action-exposure-gate, mcp-validate-expression +- ai · Skill instructions are projected onto MCP prompts · ai · skill-instructions-mcp-prompts +- ai · What the community edition lacks it honestly says it lacks, and the UI puts up no empty shell · ai · open-edition-honest-degradation, console-ai-surface-gating +- identity · Give an agent a personal key: shown once, revocable and restorable · identity-auth · api-key-ui-lifecycle + +**⑥ Iterate once on a one-sentence customer request** + +- studio · The first-run loop: create a package → create an object → records → an app → publish → end user, zero code and zero restarts · studio-authoring · first-run-loop +- records · Bring the customer's existing data in: encoding, mapping, transforms, undo and cancel · records-forms · import-wizard-encoding-and-hints, named-import-mapping, import-job-undo-cancel, import-transform-matrix +- devpath · Structural changes an iteration brings: a dev boot self-heals only the safe part, and production takes no liberties · cli · dev-automigrate-policy + +**Priority**: +1. Security and data integrity always come first and do not wait for the road. +2. The road broken, or a capability on the checklist broken ⇒ P0/P1; runs but goes wrong ⇒ P2; neither on the road nor on the checklist ⇒ p3 or not done. Grading reads "Features on the road": change that table to change priority, ⛔ never re-grade card by card. +3. While a lane's queue still holds an open P0/P1, that lane dispatches no p2/p3 tooling card or contract-hygiene card; an instrument card that unblocks a product P0/P1 inherits its priority along the chain. +4. Because AI writes it and AI uses it: the ontology must be writable by AI — what is wrong must be loudly refused with a prescription, never silently stored; and usable by people and agents — declared objects, actions and agent / tool / skill metadata are honoured at runtime, what the MCP surface exposes is what the application really can do, and an agent that oversteps is stopped by permissions and leaves a trace. The half people use has a standard too: an author who writes not one line of UI code gets a UI that looks as if a designer had handled it — one design system, one layout; looking wrong is as much a defect as failing to render, and is refused at the "see it" step. One wrong sentence in the documentation and skills written for AI is a product defect. + +**Stage posture**: speed over compatibility. Few people use it: a retirement takes effect at once, with no transition window and no alias double-spelling; compatibility layers, migration windows and the like default to p3; keys declared but not honoured are retired in batches per release, not one card per key. + +**Instruments serve the fleet**: a card that changes the PM protocol, a gate, a ratchet or a skill is graded by "which decision or action of the fleet will differ once it lands" — if that can be said (a dispatch that would otherwise have gone wrong, a landing that could not land, a review that let a fake through, a seat that got stuck), it is graded by the rules above and competes with product cards on the same field; if it cannot be said, it is not done. + +**Not now**: the cloud service's journey (sign-up, control plane, hosting) has its own checklist; the enterprise edition's built-in agent belongs to the cloud repository and is not on this repository's road or checklist; billing is not built. + +**The ledger**: the ledger of capabilities and verification is `docs/qa/platform-checklist/`, and this page does not copy it. This page carries no numbers; numbers come from commands. diff --git a/docs/qa/platform-checklist/README.md b/docs/qa/platform-checklist/README.md index 8c17d9e18d9..8a8bca71867 100644 --- a/docs/qa/platform-checklist/README.md +++ b/docs/qa/platform-checklist/README.md @@ -302,7 +302,7 @@ Three things worth knowing before you meet it: The ledger used to record only capabilities that already work, so a missing piece of a listed capability had nowhere to live: the backlog sweep had nothing to point a `Path:` at, and the platform's implementation status lived in nobody's head. The North Star's -definition line (「做出来的是什么」…「缺任何一样就不是这个应用」) makes such a piece a +definition line ("What gets built" … "missing any one of these, it is not this application") makes such a piece a **requirement**, so it belongs on the ledger — as a fourth status, not as a second document. A separate feature list drifts against this one the moment either is edited, and nothing can then say which of the two is wrong: there is no ratchet between two diff --git a/packages/lint/src/validate-security-posture.runtime-surface.test.ts b/packages/lint/src/validate-security-posture.runtime-surface.test.ts index af63518da82..2fc65c8818d 100644 --- a/packages/lint/src/validate-security-posture.runtime-surface.test.ts +++ b/packages/lint/src/validate-security-posture.runtime-surface.test.ts @@ -45,8 +45,8 @@ // (batch #203 item 3, letter B, 「203 同意」) REFUSED the other way out of // that state: retiring `allowRuntimeCreate` on the two types would close // Studio's own app designer, a shipped tenant capability, so the rules are -// made real on every door instead (`docs/NORTH-STAR.md` 〈优先级〉 4 -// 「声明了的…在运行时兑现」; ADR-0010). The snapshot did NOT grow to carry +// made real on every door instead (`docs/NORTH-STAR.md` 〈Priority〉 4, +// "declared … honoured at runtime"; ADR-0010). The snapshot did NOT grow to carry // `positions` / `apps`: this rule resolves no references across // collections, so mapping the two write types was the whole unblock. // @@ -312,7 +312,7 @@ describe('validateSecurityPosture at the runtime publish surface (#7576 → #830 // other way out of that state — retiring `allowRuntimeCreate` on the two // types would close Studio's own app designer, a shipped tenant // capability — and ruled the rules real on every door instead - // (`docs/NORTH-STAR.md` 〈优先级〉 4 「声明了的…在运行时兑现」; ADR-0010). + // (`docs/NORTH-STAR.md` 〈Priority〉 4, "declared … honoured at runtime"; ADR-0010). // // So the premise the old pin rested on is gone, not relaxed: the only rule // that judges these two collections is `security-role-word`, and it now diff --git a/scripts/pm/ensure-pm-labels.sh b/scripts/pm/ensure-pm-labels.sh index 1e025a34c4c..7ed3b6f63e5 100644 --- a/scripts/pm/ensure-pm-labels.sh +++ b/scripts/pm/ensure-pm-labels.sh @@ -568,7 +568,7 @@ gh label create domain:ui -R objectstack-ai/objectui -c bfd4f2 -d "objectui ui l # The FEATURE AXIS — `area:*`, one per card, eleven values. It is the PLANNING # axis: priority is judged on it, and `domain:*` beside it decides only which # seat may claim which files. The eleven values are the North Star definition -# line (「做出来的是什么」) plus the road it measures, so the axis and the +# line ("What gets built") plus the road it measures, so the axis and the # product definition cannot drift apart without one of them being edited. # The eleven were put to the maintainer on the charter card and confirmed there # (2026-09-21) with ONE amendment: the API/integration value was shortened to @@ -592,7 +592,7 @@ gh label create domain:ui -R objectstack-ai/objectui -c bfd4f2 -d "objectui ui l # # TWO repos, deliberately, and not the five-repo loop above: a feature point # spans 协议 → 运行时 → 前端, which is objectstack plus objectui. cloud is -# parked (北极星「现在不做」), objectos is the docs/site repo, and hotcrm is the +# parked (North Star "Not now"), objectos is the docs/site repo, and hotcrm is the # exemplar APP — its cards are app cards, and a platform gap found there is # filed in the platform repo, where it gets its area. Widening the loop is a # vocabulary decision, not a maintenance edit. diff --git a/ui/packages/types/src/__tests__/plugin-component-input-deprecation.test.ts b/ui/packages/types/src/__tests__/plugin-component-input-deprecation.test.ts index 3f2240d0e1d..da3bbd3576f 100644 --- a/ui/packages/types/src/__tests__/plugin-component-input-deprecation.test.ts +++ b/ui/packages/types/src/__tests__/plugin-component-input-deprecation.test.ts @@ -21,7 +21,7 @@ * 404, so the deletion had no carrier and the card sat on hold with no * `Restart-when:`. Execution ruling, 2026-09-27 (triage comment 5857459542, * carrying the maintainer's 「同意」): delete now rather than wait on a dead - * carrier — `docs/NORTH-STAR.md` 〈阶段姿态〉 makes immediate retirement (no + * carrier — `docs/NORTH-STAR.md` 〈Stage posture〉 makes immediate retirement (no * alias, no window) the default once a name has zero consumers, and the * window this deprecation bought has already been spent. * From e2b41f708eaed1c98a286e7c83054649c2dc70b8 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 1 Nov 2026 23:51:00 +0000 Subject: [PATCH 2/2] =?UTF-8?q?docs(north-star):=20=E4=B8=8D=E5=81=9A=20re?= =?UTF-8?q?ads=20"not=20taken=20on",=20and=20the=20clause-4=20quotes=20fol?= =?UTF-8?q?low=20the=20English=20text?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Priority 2 and Instruments serve the fleet rendered 不做 as "not done", which an English-only triage reader could take as "cannot be marked done" (hold) where the rule means close; both now read "not taken on", with "done" left to What counts as done. Five code comments quoted the retired Chinese clause-4 sentence verbatim; each now quotes the sentence as the file spells it, so a grep of the quoted words finds the governing text again. Co-Authored-By: Claude Claude-Session: https://claude.ai/code/session_017ihL2g7RyXa8ErM6GAkHyc --- docs/NORTH-STAR.md | 4 ++-- packages/metadata-protocol/src/protocol-package-install.ts | 4 ++-- .../src/domains/packages-install-manifest-id.test.ts | 3 ++- .../src/domains/packages-install-manifest-version.test.ts | 3 ++- packages/runtime/src/domains/packages.ts | 6 ++++-- 5 files changed, 12 insertions(+), 8 deletions(-) diff --git a/docs/NORTH-STAR.md b/docs/NORTH-STAR.md index b36e9168ab3..71486b95f27 100644 --- a/docs/NORTH-STAR.md +++ b/docs/NORTH-STAR.md @@ -112,13 +112,13 @@ **Priority**: 1. Security and data integrity always come first and do not wait for the road. -2. The road broken, or a capability on the checklist broken ⇒ P0/P1; runs but goes wrong ⇒ P2; neither on the road nor on the checklist ⇒ p3 or not done. Grading reads "Features on the road": change that table to change priority, ⛔ never re-grade card by card. +2. The road broken, or a capability on the checklist broken ⇒ P0/P1; runs but goes wrong ⇒ P2; neither on the road nor on the checklist ⇒ p3 or not taken on. Grading reads "Features on the road": change that table to change priority, ⛔ never re-grade card by card. 3. While a lane's queue still holds an open P0/P1, that lane dispatches no p2/p3 tooling card or contract-hygiene card; an instrument card that unblocks a product P0/P1 inherits its priority along the chain. 4. Because AI writes it and AI uses it: the ontology must be writable by AI — what is wrong must be loudly refused with a prescription, never silently stored; and usable by people and agents — declared objects, actions and agent / tool / skill metadata are honoured at runtime, what the MCP surface exposes is what the application really can do, and an agent that oversteps is stopped by permissions and leaves a trace. The half people use has a standard too: an author who writes not one line of UI code gets a UI that looks as if a designer had handled it — one design system, one layout; looking wrong is as much a defect as failing to render, and is refused at the "see it" step. One wrong sentence in the documentation and skills written for AI is a product defect. **Stage posture**: speed over compatibility. Few people use it: a retirement takes effect at once, with no transition window and no alias double-spelling; compatibility layers, migration windows and the like default to p3; keys declared but not honoured are retired in batches per release, not one card per key. -**Instruments serve the fleet**: a card that changes the PM protocol, a gate, a ratchet or a skill is graded by "which decision or action of the fleet will differ once it lands" — if that can be said (a dispatch that would otherwise have gone wrong, a landing that could not land, a review that let a fake through, a seat that got stuck), it is graded by the rules above and competes with product cards on the same field; if it cannot be said, it is not done. +**Instruments serve the fleet**: a card that changes the PM protocol, a gate, a ratchet or a skill is graded by "which decision or action of the fleet will differ once it lands" — if that can be said (a dispatch that would otherwise have gone wrong, a landing that could not land, a review that let a fake through, a seat that got stuck), it is graded by the rules above and competes with product cards on the same field; if it cannot be said, it is not taken on. **Not now**: the cloud service's journey (sign-up, control plane, hosting) has its own checklist; the enterprise edition's built-in agent belongs to the cloud repository and is not on this repository's road or checklist; billing is not built. diff --git a/packages/metadata-protocol/src/protocol-package-install.ts b/packages/metadata-protocol/src/protocol-package-install.ts index 2e4cbb861e6..a64be534f6b 100644 --- a/packages/metadata-protocol/src/protocol-package-install.ts +++ b/packages/metadata-protocol/src/protocol-package-install.ts @@ -146,8 +146,8 @@ export async function installPackage( // while `defineStack()`, `os build`, `os validate` and the publish face // all refuse the same id. That is «declared ≠ enforced» on a PUBLISHED // contract, the shape Prime Directive #10 refuses outright and - // 北极星 clause 4 names in as many words: - // 「错的必须被**响亮拒绝**并给处方,**永不静默落库**」. + // 北极星 clause 4 names in as many words: "what is wrong must be loudly + // refused with a prescription, never silently stored". // // ⭐ THE GATE IS ON THE PRIMITIVE, NOT ON ONE DOOR. #19473 landed the // same parse at `POST /packages` diff --git a/packages/runtime/src/domains/packages-install-manifest-id.test.ts b/packages/runtime/src/domains/packages-install-manifest-id.test.ts index 291dd31513c..7c3ae08f161 100644 --- a/packages/runtime/src/domains/packages-install-manifest-id.test.ts +++ b/packages/runtime/src/domains/packages-install-manifest-id.test.ts @@ -16,7 +16,8 @@ * the same id. The author got a package that could never be rebuilt or * published — «declared ≠ enforced» on a PUBLISHED API contract, which Prime * Directive #10 refuses outright, and the exact failure 北极星 clause 4 names: - * 「错的必须被**响亮拒绝**并给处方,**永不静默落库**」. + * "what is wrong must be loudly refused with a prescription, never silently + * stored". * * The authorising ruling is 基本裁决原则 — * 「spec 声明 > 实现 > 文档面;**声明而未兑现是实现缺口,补实现或退役**, diff --git a/packages/runtime/src/domains/packages-install-manifest-version.test.ts b/packages/runtime/src/domains/packages-install-manifest-version.test.ts index f1c921ef1fa..80266b256e9 100644 --- a/packages/runtime/src/domains/packages-install-manifest-version.test.ts +++ b/packages/runtime/src/domains/packages-install-manifest-version.test.ts @@ -14,7 +14,8 @@ * with no `version` at all installed and the door answered `201` — «declared ≠ * enforced» on a PUBLISHED API contract, which Prime Directive #10 refuses * outright, and the exact failure 北极星 clause 4 names: - * 「错的必须被**响亮拒绝**并给处方,**永不静默落库**」. + * "what is wrong must be loudly refused with a prescription, never silently + * stored". * * The authorising ruling is 基本裁决原则 — * 「spec 声明 > 实现 > 文档面;**声明而未兑现是实现缺口,补实现或退役**, diff --git a/packages/runtime/src/domains/packages.ts b/packages/runtime/src/domains/packages.ts index 5488c8893cf..c77bd282798 100644 --- a/packages/runtime/src/domains/packages.ts +++ b/packages/runtime/src/domains/packages.ts @@ -1497,7 +1497,8 @@ export async function handlePackagesRequest(deps: DomainHandlerDeps, path: strin // never be rebuilt or published — «declared ≠ enforced» on a // PUBLISHED API contract, the shape Prime Directive #10 refuses // outright, and the failure 北极星 clause 4 names in as many words: - // 「错的必须被**响亮拒绝**并给处方,**永不静默落库**」. + // "what is wrong must be loudly refused with a prescription, never + // silently stored". // // The authorising ruling is 基本裁决原则 —「声明而未兑现是实现缺口, // 补实现或退役,⛔ 不在消费端收窄」— and by the mechanical boundary @@ -1570,7 +1571,8 @@ export async function handlePackagesRequest(deps: DomainHandlerDeps, path: strin // `version` installed and answered `201`. That is «declared ≠ // enforced» on a PUBLISHED API contract — the shape Prime Directive // #10 refuses outright — and it is the failure 北极星 clause 4 names - // in as many words: 「错的必须被**响亮拒绝**并给处方,**永不静默落库**」. + // in as many words: "what is wrong must be loudly refused with a + // prescription, never silently stored". // So the refusal is loud and carries the prescription. // // The ruling that authorises it is 基本裁决原则 —