From 1d661f7a5695f0ef1364e1fae5874d106f855bd9 Mon Sep 17 00:00:00 2001 From: brother7 <7brother7@gmail.com> Date: Sat, 12 Sep 2026 22:14:51 +0800 Subject: [PATCH] docs: record model capability main branch delivery --- ...-2026-09-12-official-model-capabilities.md | 19 ++++++++ .project-docs/10-decisions/decision-index.md | 2 + .project-docs/20-architecture/data-flow.md | 4 ++ .../20-architecture/system-overview.md | 12 ++--- .project-docs/30-worklog/current-state.md | 2 + ...260912-land-model-capabilities-c6fa4309.md | 48 +++++++++++++++++++ .project-docs/40-domain/business-rules.md | 6 +++ 7 files changed, 87 insertions(+), 6 deletions(-) create mode 100644 .project-docs/10-decisions/ADR-2026-09-12-official-model-capabilities.md create mode 100644 .project-docs/30-worklog/tasks/20260912-land-model-capabilities-c6fa4309.md diff --git a/.project-docs/10-decisions/ADR-2026-09-12-official-model-capabilities.md b/.project-docs/10-decisions/ADR-2026-09-12-official-model-capabilities.md new file mode 100644 index 00000000..9e3d2e3e --- /dev/null +++ b/.project-docs/10-decisions/ADR-2026-09-12-official-model-capabilities.md @@ -0,0 +1,19 @@ +# 官方模型能力与原生思考选项 + +- 状态：Accepted / implemented；用户已批准设计、实施及三端主分支合并。 +- 日期：2026-09-12 +- 源提交：26cbb29；合并：2888aaed；源任务记录保持只读。 + +## 决策 + +one-api 按渠道、映射后的模型身份，从百炼和原生 DeepSeek 官方接口/文档获取能力事实。输入与输出模态、思考支持、能否关闭、默认状态、原生 effort 值和限制分开表达；未知不等于 false 或空列表。可用目录按实际 gateway group 汇总全部候选及回退渠道的共同能力。Works Square 存储完整快照并应用模型激活和用户授权，通过 model_capabilities_v2 下发；运营只查看和刷新能力事实。 + +Makelore 的受管模型使用 v2 作为图片输入与思考选项权威。缺失或非法事实保持未知，不从模型名称或本地 profile 推测。BYOK 保持原有配置，Web Search 继续采用独立的已验证适配器政策。服务端 v1 保留给仍受支持的旧客户端。 + +产品模型配置独立保存 reasoningChoice：default、disabled，或 enabled 加可选的供应商原生 effort 字符串。Pi 的固定枚举只是内部载体，不能丢失 xhigh 等值。模型切换重置为 default；Main 在接收 prompt 前验证选择和图片输入，将准备好的供应商字段冻结到父/子运行上下文。Pi before_provider_request 钩子清理 SDK 注入的思考字段，再应用本次冻结字段。default 省略控制字段，不能隐式发送关闭。 + +## 验证与交付边界 + +源提交通过 70 项相关测试、类型检查、Vite 构建、真实 Pi 本地 HTTP 序列化和 Electron 用例。合入主分支的知识库/云智能体界面后，57 项相关测试、类型检查、Vite 全目标构建及受管模型 Electron 用例再次通过。既有 Main TypeScript 的 61 项诊断已在源任务中证明没有新增。 + +先部署 one-api，再迁移/部署 Works Square，最后发布匹配客户端。真实账号目录权限、group 与供应商推理仍须发布环境验收；本次未推送、打包或部署。首期为文本/图片与思考控制；可选 budget 字段保留，未解析事实保持未知，不增加 budget 编辑器。 diff --git a/.project-docs/10-decisions/decision-index.md b/.project-docs/10-decisions/decision-index.md index 8deb3992..2e26b425 100644 --- a/.project-docs/10-decisions/decision-index.md +++ b/.project-docs/10-decisions/decision-index.md @@ -2,6 +2,8 @@ ## Active Decisions +- [官方模型能力与原生思考选项](ADR-2026-09-12-official-model-capabilities.md)：2026-09-12 accepted / implemented；one-api 官方事实、Works v2 授权投影、受管模型图片输入与 Main-owned reasoningChoice，取代受管模型的静态推测与 Pi 枚举映射。 + - [个人云智能体平台](ADR-2026-09-11-personal-cloud-agents.md)：2026-09-11 accepted / implemented，2026-09-12 补充桌面编辑工作区；三端分工、创建者付费、保存与试用版本分离、恢复/资源/独立预算及发布证据边界。 | ID | Decision | Status | Date | Applies To | Detail | diff --git a/.project-docs/20-architecture/data-flow.md b/.project-docs/20-architecture/data-flow.md index 5bdae786..c888b11c 100644 --- a/.project-docs/20-architecture/data-flow.md +++ b/.project-docs/20-architecture/data-flow.md @@ -1,5 +1,9 @@ # Data Flow +## Managed model capability flow + +one-api 官方接口/文档事实与实际 group 路由交集 -> Works 完整快照和业务授权 -> model-config v2 -> Main 安全 Provider metadata -> 产品 reasoningChoice/图片输入校验 -> 冻结父/子运行上下文 -> Pi 请求钩子清除 SDK 控制字段并写入原生字段。Renderer 消费相同能力投影，缺失事实不做名称推测；详情见[官方能力决策](../10-decisions/ADR-2026-09-12-official-model-capabilities.md)。 + ## Primary Flows | Flow | Source | Destination | Notes | diff --git a/.project-docs/20-architecture/system-overview.md b/.project-docs/20-architecture/system-overview.md index 6e3f85ea..16e37389 100644 --- a/.project-docs/20-architecture/system-overview.md +++ b/.project-docs/20-architecture/system-overview.md @@ -28,7 +28,7 @@ Makelore 是 Electron 桌面客户端。Renderer 负责项目操作与状态展 | Makelore Code Workspace | project/Agent/Conversation schema v2、产品中立 Snapshot/Patch、Composer 与时间线 | Conversation 本地创建且不等待 worker；sleep 关闭旧 SSE，视图挂载、项目切换、visibility/focus 会静默刷新已选 Snapshot；旧 OpenCode 会话备份后不再继续，Renderer 不导入 Pi RPC/event 类型 | | Coding Host API & Composition | 唯一 `/api/coding/*` composition、202 acceptance/dedupe、SSE、附件/文件/交互/诊断 | Electron Main 拥有 project/Conversation 服务、选中目标、认证和错误脱敏；SSE 公开面只有 Snapshot 与 `patch-batch` | | Pi Conversation Runtime | 一个长驻 Pi `0.84.2` Agent Server 承载每条 active/warm Conversation 的隔离逻辑 Runtime/Session/JSONL channel | 严格 LF JSONL RPC、generation recovery、Snapshot hydration；正式包从 staged `pi-runtime` manifest/root 定位并校验 Pi 包入口；top-level 逻辑 turn 并发 4、warm idle LRU 8；Server 退出统一使旧 channel 失效并按需单实例重启 | -| Pi Provider & Managed Resources | Provider catalog、thread-local secret projection、model/resource revision、Prompt/Skill/extension materialization、selected-model tools | 父凭据只进入选中逻辑线程的内存 credential store，child 凭据只进入该短命进程；Works `model_capabilities` 由 Main 严格归一化并作为安全 Provider metadata 持久化。Web Search 仅在精确 capability 存在时随冻结的 selected model/provider/credential 进入 parent tool catalog，并走普通模型计费；不回退 `agent_browser` 或独立 Hosted Provider。服务端 reasoning levels 优先于本地 profile，缺字段则清理 override 并回退；不扫描项目或用户的 `.pi/.agents/.codex`，不把 secret 或原始响应放进 argv、catalog 或 Renderer | +| Pi Provider & Managed Resources | Provider catalog、thread-local secret projection、model/resource revision、Prompt/Skill/extension materialization、selected-model tools | Works `model_capabilities_v2` 由 Main 归一化并持久化，作为受管模型图片/思考能力唯一依据；未知不回退本地 profile。Main 保存原生 reasoningChoice 并冻结供应商字段，经 Pi 请求钩子发送。父/子凭据仍限于目标执行上下文；Web Search 保持独立适配器、所选模型及普通模型计费，不回退 agent_browser；secret 不进入 argv、catalog 或 Renderer | | Pi Extension, Subagents & Lifecycle | 必需的生成式 Makelore extension、Main 显式选定的已安装 extensions、UI interaction、ephemeral child、write lease 与 background run lease | Makelore bridge 固定为首个 extension，其余选定 extension 全部经 Pi 的 explicit additional paths 加载且 ambient discovery 关闭；child 并发 4、单次最多 8、禁止递归；active/uncertain run 不因页面隐藏或 confirmation timeout 被停止，replacement/stop 必须可解释并清理所有 ownership | | Shared Agent Browser | Project-scoped sandboxed `WebContentsView`、Renderer 右侧面板与 Main-owned CDP bridge | 用户和 Agent 操作同一页面；Renderer 必须先提供可见 bounds，Agent `open` 最多等待 5 秒取得可见 viewport。Console/Network 诊断按 owner 引用计数；关闭面板、切换项目/模块、隐藏窗口或后台休眠会清理 view、debugger 与轮询。 | | Code-owned Official Project Plugins | Existing Account acquisition or system-included delivery → project enablement → effective parent snapshot | Data Service、Game Resource 与 Project Scaffold 都不要求 Agent assignment，项目启用后自动进入每个父 Agent；child 不继承 Plugin。三者不经过设备下载、更新、Beta 或 artifact 签名；Game Resource 的一次确认由 Main 提交一次、内部轮询并把全部终态输出自动写入冻结的原项目，恢复本地交付不得重新生成或计费；Project Scaffold 的 `.mjs` 仍只来自签名客户端固定资源。需要分配的 Marketplace 下载包保持原规则。 | @@ -69,11 +69,11 @@ Makelore 是 Electron 桌面客户端。Renderer 负责项目操作与状态展 - 正式包中的 Agent Server 必须以显式 staged `pi-runtime` 的 manifest/root 解析 Pi 依赖，校验导入入口未逃逸对应包目录；不得依赖脚本相邻目录、应用 `node_modules` 或系统包解析作为 fallback。 - 父 Pi worker 与 Agent Server 必须获得应用选择且不可被 worker overlay 覆盖的 `MAKELORE_NODE_EXECUTABLE`。包含脚本的 Device Package Skill 只能显式使用该 Node 路径，不得依赖系统 PATH。 - selected Provider credential 只投影到目标父逻辑线程的内存 credential store 或目标 child 进程；跨账号模型变化必须重建目标逻辑线程。确定性 Works user-context 缺失是 Provider-auth failure：失效缓存 credential、fail fast、固定脱敏提示，不得归类为 Pi crash。 -- Works 下发的 per-model reasoning capability 是可选 Main-owned metadata，不是 - Renderer 或 one-api 的权威。存在时只接受受支持的安全形状并覆盖目标模型的 - 本地 effort map；缺失时移除旧 override 并使用已验证本地 profile。`off` 在 Pi - wire 上表示 `thinking.type=disabled` 且不发送 `reasoning_effort`，启用档位保持 - provider 原生值，当前 DeepSeek 产品投影为 `off`/`low`/`high`/`max`。 +- one-api 获取官方能力事实，Works 应用业务权限后下发 v2，Main 负责归一化、 + 持久化与运行前校验。受管模型缺失能力保持未知，不使用模型名推测。 + reasoningChoice 保存 default/disabled/enabled 与可选原生 effort，独立于 Pi + 枚举；Main 冻结每次运行的供应商字段，Pi 钩子在请求时应用。default 不发送 + 控制字段；关闭及启用遵循实际 control_format。BYOK 和 Web Search 保持独立。 - Guided Hotspot Binding is implemented behind a Main-owned capability that is true by default; exact `NIANCODE_AI_HARDWARE_GUIDED_HOTSPOT_BINDING=0` disables it, while capability-read failure falls back to direct six-digit Binding. The guided state is process-local, opener failures expose only the same fixed address for manual copy, and Binding conflicts refresh the safe account overview. - Robot hotspot scanning and connection are local Main operations that return before Works credentials/upstream access. Renderer may submit only an opaque candidate ID from the latest bounded scan; Main alone filters open printable `Xiaozhi-*` SSIDs, performs platform association, and verifies the exact current SSID. - Hotspot discovery and connection do not authenticate a Robot. BSSID, interface/profile details, native diagnostics, location data, and Wi-Fi credentials never cross the Main boundary; permission or platform failure keeps the system-settings/manual path available. diff --git a/.project-docs/30-worklog/current-state.md b/.project-docs/30-worklog/current-state.md index 9cd38a7e..b434fb69 100644 --- a/.project-docs/30-worklog/current-state.md +++ b/.project-docs/30-worklog/current-state.md @@ -4,6 +4,8 @@ This file is the integrated default-branch snapshot. Feature tasks record progre ## Integrated Through +- 2026-09-12：任务 `20260912-land-model-capabilities-c6fa4309` 经用户授权交接主目录及集成锁，将模型能力源 `26cbb29` 合入本地 main，合并为 `2888aaed`；保留已有知识库和云智能体界面。受管模型采用 Works v2 官方能力，Main 持久化并验证原生 reasoningChoice、冻结供应商控制字段，图片附件与 Pi input 一致。合并后 57 项相关测试、类型检查、Vite 全目标构建、Electron 受管模型用例 1 项通过；源任务验证保持有效。3 份原有未跟踪记录原样保留，未推送、打包、部署或清理工作区。见[官方模型能力决策](../10-decisions/ADR-2026-09-12-official-model-capabilities.md)。 + - 2026-09-12：任务 `20260912-merge-kb-embedding-49e2b6c` 在用户确认主目录占用移交后，将本地 main 从 `a0b869a` 无冲突快进到知识库修复源 `3507f70e114be94913c72aa9e70eb6f9455cd86d`。创建知识库明确区分模型目录加载/失败/空状态，提供管理员配置说明及原地刷新；刷新保留名称，未知创建继续复用原请求身份。模型由平台管理员在 Yuxi 定义并启用（含维度）、在 Works Square 激活相同模型 ID，one-api 提供实际向量接口。客户端继续消费 Main Host API。源 50 项相关测试、类型检查、scoped ESLint、Vite 构建和 Windows Electron fixture 1 项通过；快进合并未改写产品代码，复用源验证。原有 3 个未跟踪文档保留；未推送、打包或部署，线上具体配置缺口及真实收费调用未验证。 - 2026-09-12：任务 `20260912-merge-agent-draft-d960aa87` 经用户明确同意释放旧任务占用并保留 3 份原有未跟踪记录，将本地 main 从 `70fa916` 无冲突快进到 `dca6deab292028c9f3cfd097a8c52ba0d43b35a9`。Agents 采用账号级全高桌面分栏，指令/能力/知识/限制分类，保存与试用修订分离、独立费用保存及后台会话未读保护；详情见[个人云智能体决策](../10-decisions/ADR-2026-09-11-personal-cloud-agents.md)。源最终 65 项相关测试、类型检查、scoped ESLint、Vite 构建和 Windows Electron 大小窗口/内容缩放验收通过；合并未改写产品代码，复用这些验证证据。尚未推送、制作安装包或更新已安装客户端。 diff --git a/.project-docs/30-worklog/tasks/20260912-land-model-capabilities-c6fa4309.md b/.project-docs/30-worklog/tasks/20260912-land-model-capabilities-c6fa4309.md new file mode 100644 index 00000000..7960bf67 --- /dev/null +++ b/.project-docs/30-worklog/tasks/20260912-land-model-capabilities-c6fa4309.md @@ -0,0 +1,48 @@ +# Task: Land approved model capability integration on main + +## Identity + +- Task ID: 20260912-land-model-capabilities-c6fa4309 +- Mode: Integration +- Branch: main +- Worktree: D:\Datas\OthersProjects\makelore +- Base commit: a06909e78b5e2138f29698a2222aea2cc879dc9e +- Owner: codex +- Status: Ready for Integration + +## Scope + +- Land approved model capability source 26cbb29 onto local main; reconcile canonical memory and preserve pre-existing records. + +## Intent And Constraints + +- User explicitly authorized handoff of all three primary checkout owners/integration locks and preservation/reconciliation of pending documents. Bundled release --force and start --adopt-existing succeeded; status matches this task, Integration mode, primary worktree, branch and base. +- Concurrent and Planning Gates Passed: entry, own task, memory/positioning/current-state/decisions/architecture and relevant evidence/reflection/commitments loaded; source outcomes/promotions and peer scopes assessed. Reuse unchanged baseline memory; historical placeholders remain unknown without a concrete dependency. Makelore positioning placeholders are supplemented by README and ADR-006. +- Prepared integration locks were released via the loaded bundled release_integration_lock function while retaining their ready managed ownership. This task holds the main integration lock. No subagents, push, deployment, paid inference or worktree deletion; unrelated failed knowledge cleanup is not retried. +- Source task and supporting records remain read-only. Existing foreign task documents remain unchanged/uncommitted; one-api canonical notes and gate assets may be preserved in an explicit documentation commit under the user's handoff approval. + +## Outcome + +- Local main merged source 26cbb29 as 2888aaed without conflicts, retaining existing knowledge and cloud-agent UI updates. +- Accepted v2 authority, native reasoningChoice and Main/Pi request preparation into ADR, decision index, architecture/data flow/domain and current-state. +- Three original untracked task documents remain byte-for-byte unchanged and uncommitted. + +## Verification + +- Final working/committed delta reviewed; git diff whitespace and bundled task-aware documentation drift checks passed. Source records and preserved foreign documents satisfy the gate. This Ready record is committed with the handoff; bundled complete follows. + +- Integrated main passed 57 focused tests in seven files covering managed capabilities, provider/runtime/import plus the independently merged knowledge/cloud-agent UI. +- Renderer typecheck, all Vite build targets and actual Electron managed-capability test (native xhigh choice and blocked unsupported image input) passed. +- Source 70-test/Pi HTTP/Electron verification remains valid; the 61 pre-existing additional Main tsc diagnostics were already compared to baseline with zero additions. No paid provider test or installed-package claim. +- Source ancestry and changed-path inspection confirm the pre-existing main UI commits are retained. Original foreign task records were compared directly and unchanged. + +## Follow-ups + +- Awaiting optional cleanup confirmation: source 20260912-model-capabilities-c48271f9, D:\Datas\OthersProjects\.codex-worktrees\makelore\20260912-model-capabilities-c48271f9, branch codex/20260912-model-capabilities-c48271f9-model-capabilities. Its latest result is included in actual main; confirm clean/ready/managed eligibility before retire. +- The unrelated failed knowledge retirement and its residual directory/registration remain unchanged. The unused checkout from the failed capability integration start is unowned/unmanaged and is retained, not offered for automatic retirement. +- Worktree cleanup removes ignored dependencies/build output but preserves branches/commits. No cleanup has been authorized or executed by this handoff. No push, package, deployment, migration of a deployed database or paid inference. +- Release order remains one-api -> Works migration/deployment -> matching Makelore release; real account catalog/group and provider inference are deployment acceptance. + +## Promotion Candidates + +- Approved source capability contract promoted into canonical memory; actual main landing recorded. No unresolved product decision. diff --git a/.project-docs/40-domain/business-rules.md b/.project-docs/40-domain/business-rules.md index 41f0844e..a437317f 100644 --- a/.project-docs/40-domain/business-rules.md +++ b/.project-docs/40-domain/business-rules.md @@ -1,5 +1,11 @@ # Business Rules +## Managed model capabilities + +- 受管模型的图片输入与思考选项来自 Works v2 官方能力投影，未知、false 和空原生 effort 列表分开处理，不靠本地模型清单推测。运营激活与能力事实分离。 +- Main 在 prompt 前校验并保存 reasoningChoice，保留任意已声明原生 effort；default 省略供应商控制字段，disabled 只在供应商支持时提供。父/子运行使用冻结上下文，Renderer 与 Pi model.input 使用同一模态依据。 +- BYOK、本地配置以及独立 Web Search 适配器策略不受本项取代；首期没有 budget 编辑器。 + ## Durable Rules - Marketplace Release A is curated: only Operations publishes packages. Users may