| 1 | /** |
| 2 | * vocabulary.ts — shared, locale-aware product vocabulary for codewhale.net. |
| 3 | * |
| 4 | * This module is the single source of truth for the exact product nouns a new |
| 5 | * user meets on the site: the Fleet/Workflow/Lane/Runtime execution nouns, |
| 6 | * the Plan/Act/Operate + Ask/Auto-Review/Full Access control vocabulary, the |
| 7 | * public Consultant role, and the fields that make route provenance legible. |
| 8 | * |
| 9 | * TRUTH CONTRACT: |
| 10 | * - `short.en` for every product term MUST equal the verbatim definition in |
| 11 | * docs/public-surface-facts.json → product.terminology, which is itself |
| 12 | * pinned verbatim against docs/FLEET.md by public-surface-contract.test.ts. |
| 13 | * - Mode and posture names MUST equal matrix.control.modes / |
| 14 | * matrix.control.permissionPostures (pinned against docs/MODES.md). |
| 15 | * - No marketing adjectives. Each description states behavior and boundary. |
| 16 | * |
| 17 | * EXTENSION PATH FOR NEW LOCALES (localization lane): |
| 18 | * Every user-facing string is a `{ en, zh }` pair. Add the new locale key to |
| 19 | * each pair (and widen the `LocalizedText` type) — the consuming components |
| 20 | * and tests pick it up without structural changes. The tests assert key |
| 21 | * parity across locales, so a missing translation fails deterministically. |
| 22 | */ |
| 23 | |
| 24 | export interface LocalizedText { |
| 25 | en: string; |
| 26 | zh: string; |
| 27 | } |
| 28 | |
| 29 | export interface ProductTerm { |
| 30 | /** The exact product noun. Never translate the noun itself. */ |
| 31 | term: "Fleet" | "Workflow" | "Lane" | "Runtime"; |
| 32 | /** One-line definition; `en` is verbatim from docs/public-surface-facts.json. */ |
| 33 | short: LocalizedText; |
| 34 | /** One-sentence elaboration used on docs pages. */ |
| 35 | long: LocalizedText; |
| 36 | } |
| 37 | |
| 38 | export const PRODUCT_TERMS: ProductTerm[] = [ |
| 39 | { |
| 40 | term: "Fleet", |
| 41 | short: { en: "who does the work", zh: "谁来做工作" }, |
| 42 | long: { |
| 43 | en: "Who does the work: the configured workers, roles, models, hosts, and trust boundaries.", |
| 44 | zh: "谁来做工作：配置好的 worker、角色、模型、主机和信任边界。", |
| 45 | }, |
| 46 | }, |
| 47 | { |
| 48 | term: "Workflow", |
| 49 | short: { en: "what order the work follows", zh: "工作按什么顺序进行" }, |
| 50 | long: { |
| 51 | en: "What order the work follows: phases, gates, budgets, replay, and fan-in.", |
| 52 | zh: "工作按什么顺序进行：阶段、门禁、预算、回放和汇总。", |
| 53 | }, |
| 54 | }, |
| 55 | { |
| 56 | term: "Lane", |
| 57 | short: { en: "one running Workflow instance", zh: "一个正在运行的 Workflow 实例" }, |
| 58 | long: { |
| 59 | en: "One running Workflow instance and its live progress.", |
| 60 | zh: "一个正在运行的 Workflow 实例及其实时进度。", |
| 61 | }, |
| 62 | }, |
| 63 | { |
| 64 | term: "Runtime", |
| 65 | short: { en: "where and how a Lane executes", zh: "Lane 在哪里、如何执行" }, |
| 66 | long: { |
| 67 | en: "Where and how a Lane executes: local or remote process, provider route, sandbox, and API boundary.", |
| 68 | zh: "Lane 在哪里、如何执行：本地或远程进程、提供商路由、沙箱和 API 边界。", |
| 69 | }, |
| 70 | }, |
| 71 | ]; |
| 72 | |
| 73 | export interface ControlTerm { |
| 74 | /** The exact control noun. Never translate the noun itself. */ |
| 75 | term: string; |
| 76 | kind: "mode" | "permission-posture"; |
| 77 | /** Behavioral description aligned with docs/MODES.md. */ |
| 78 | description: LocalizedText; |
| 79 | } |
| 80 | |
| 81 | /** TUI modes — cycle with Tab when the composer is idle (docs/MODES.md). */ |
| 82 | export const CONTROL_MODES: ControlTerm[] = [ |
| 83 | { |
| 84 | term: "Plan", |
| 85 | kind: "mode", |
| 86 | description: { |
| 87 | en: "Design-first and always read-only: investigation tools stay available, shell and patch execution stay off.", |
| 88 | zh: "设计优先且始终只读：调查工具可用，shell 与补丁执行保持关闭。", |
| 89 | }, |
| 90 | }, |
| 91 | { |
| 92 | term: "Act", |
| 93 | kind: "mode", |
| 94 | description: { |
| 95 | en: "The default working mode for new sessions: multi-step tool use with approval prompts gating each shell call.", |
| 96 | zh: "新会话的默认工作模式：多步骤工具调用，每次 shell 调用都有审批提示把关。", |
| 97 | }, |
| 98 | }, |
| 99 | { |
| 100 | term: "Operate", |
| 101 | kind: "mode", |
| 102 | description: { |
| 103 | en: "Multitask conductor under the same permission posture, sandbox, and safety rules as Act; background worker dispatch is the default for real multi-step work.", |
| 104 | zh: "在与 Act 相同的权限姿态、沙箱和安全规则下进行多任务调度；真正的多步骤工作默认派发给后台 worker。", |
| 105 | }, |
| 106 | }, |
| 107 | ]; |
| 108 | |
| 109 | /** Permission postures — cycle with Shift+Tab when the composer is idle. */ |
| 110 | export const PERMISSION_POSTURES: ControlTerm[] = [ |
| 111 | { |
| 112 | term: "Ask", |
| 113 | kind: "permission-posture", |
| 114 | description: { |
| 115 | en: "The default: Codewhale asks when an unresolved choice materially changes authority, cost, scope, or outcome.", |
| 116 | zh: "默认值：当一个未决选择会实质改变权限、成本、范围或结果时，Codewhale 会询问。", |
| 117 | }, |
| 118 | }, |
| 119 | { |
| 120 | term: "Auto-Review", |
| 121 | kind: "permission-posture", |
| 122 | description: { |
| 123 | en: "Fully autonomous: never opens a user question; resolves ambiguity to a safe reversible interpretation or reports that it cannot proceed safely.", |
| 124 | zh: "完全自主：从不弹出用户提问；把歧义消解为安全可逆的解释，或明确报告无法安全继续。", |
| 125 | }, |
| 126 | }, |
| 127 | { |
| 128 | term: "Full Access", |
| 129 | kind: "permission-posture", |
| 130 | description: { |
| 131 | en: "Ordinary tool calls skip approval prompts; non-bypassable safety, repository-law, and managed-policy holds still fail closed.", |
| 132 | zh: "普通工具调用不再显示审批提示；不可绕过的安全、仓库法则和托管策略拦截仍然会失败关闭。", |
| 133 | }, |
| 134 | }, |
| 135 | ]; |
| 136 | |
| 137 | /** |
| 138 | * Route identity vocabulary. Requested and effective reasoning are separate: |
| 139 | * an adaptive request is not itself evidence of the tier a provider used. |
| 140 | * Routing source is provenance, not a provider or model substitute. Unknown |
| 141 | * effective values stay explicitly unknown. |
| 142 | */ |
| 143 | export const ROUTE_IDENTITY: { term: string; description: LocalizedText }[] = [ |
| 144 | { |
| 145 | term: "Provider", |
| 146 | description: { |
| 147 | en: "Who serves inference — a hosted API, a gateway, or a loopback local runtime (Ollama, vLLM, SGLang). A configured provider is never inferred from a model name.", |
| 148 | zh: "谁提供推理——托管 API、网关或本机回环本地运行时（Ollama、vLLM、SGLang）。绝不会根据模型名称推断已配置的 provider。", |
| 149 | }, |
| 150 | }, |
| 151 | { |
| 152 | term: "Model", |
| 153 | description: { |
| 154 | en: "The exact model on that provider. Codewhale treats models as selectable components; no provider or model is privileged over another.", |
| 155 | zh: "该提供商上的具体模型。Codewhale 把模型当作可选组件；任何提供商或模型都不享有特权。", |
| 156 | }, |
| 157 | }, |
| 158 | { |
| 159 | term: "Requested reasoning", |
| 160 | description: { |
| 161 | en: "The policy requested for the frozen route: inherit, off, low, medium, high, max, or auto. Auto permits adaptive reasoning; it never permits a silent provider or model switch.", |
| 162 | zh: "为冻结路由请求的策略：inherit、off、low、medium、high、max 或 auto。Auto 允许自适应思考，但绝不允许静默切换 provider 或模型。", |
| 163 | }, |
| 164 | }, |
| 165 | { |
| 166 | term: "Effective reasoning", |
| 167 | description: { |
| 168 | en: "The tier actually applied for the run when the runtime or provider can establish it. If it cannot be established, the value is unavailable — never copied from the request or invented.", |
| 169 | zh: "运行时或 provider 能够确认时，显示该次运行实际采用的档位；无法确认时标为暂不可用，绝不从请求值复制或臆造。", |
| 170 | }, |
| 171 | }, |
| 172 | { |
| 173 | term: "Routing source", |
| 174 | description: { |
| 175 | en: "Why this configured route was selected, such as an explicit member profile or inherited session setting. Missing provenance stays unavailable rather than being guessed.", |
| 176 | zh: "说明为何选择这条已配置路由，例如显式成员档案或继承的会话设置。缺失的来源保持暂不可用，绝不猜测。", |
| 177 | }, |
| 178 | }, |
| 179 | ]; |
| 180 | |
| 181 | /** Public advisory role vocabulary; legacy spellings are input compatibility. */ |
| 182 | export const ADVISORY_ROLE = { |
| 183 | term: "Consultant", |
| 184 | description: { |
| 185 | en: "The public read-only advisory Fleet role. The historical oracle and advisor spellings remain compatibility aliases for saved configuration and replay only; new product surfaces say Consultant.", |
| 186 | zh: "面向用户的只读 Fleet 咨询角色。历史拼写 oracle 与 advisor 仅作为已保存配置和回放的兼容别名保留；新的产品界面统一使用 Consultant。", |
| 187 | }, |
| 188 | } as const; |
| 189 | |
| 190 | /** |
| 191 | * Measurement truth — what the site may claim about benchmark-style numbers. |
| 192 | * These are policy statements, not results: the site publishes no leaderboard, |
| 193 | * and any future number must carry its exact route identity and harness. |
| 194 | */ |
| 195 | export const MEASUREMENT_PRINCIPLES: LocalizedText[] = [ |
| 196 | { |
| 197 | en: "Provider token and cache usage is shown locally when the provider reports it; unknown usage stays unknown and is never displayed as zero.", |
| 198 | zh: "当提供商上报时，token 与缓存用量会在本地显示；未知用量保持未知，绝不显示为零。", |
| 199 | }, |
| 200 | { |
| 201 | en: "Costs, progress, capabilities, and delivery state are shown only when a source establishes them. Unavailable values remain unavailable rather than becoming zero or success.", |
| 202 | zh: "成本、进度、能力和交付状态仅在有来源能够确认时显示。暂不可用的值保持暂不可用，绝不会变成零或成功。", |
| 203 | }, |
| 204 | { |
| 205 | en: "This site publishes no benchmark leaderboard. Any number Codewhale ever publishes must name its exact provider, model, requested and effective reasoning, and measurement harness alongside the result.", |
| 206 | zh: "本站不发布基准排行榜。Codewhale 今后发布任何数字时，都必须同时给出确切的提供商、模型、请求与实际思考档位和测量工具链。", |
| 207 | }, |
| 208 | ]; |
| 209 |