mirror of
https://github.com/NeuralNomadsAI/CodeNomad.git
synced 2026-11-01 03:20:37 +00:00
77c24601a8
## Summary
- OpenCode **2.2.3** becomes both the **technical minimum** and the
**recommended** runtime. The minimum moves because upstream
[#60258](https://github.com/anomalyco/opencode/pull/60258) (shipped in
2.2.2) changed the image tool contract that CodeNomad's Images gallery,
Design agent and Images settings consume: one name,
`experimental_image_generate`, for the tool, its permission action, its
job type and its completion notices' `metadata.source`, and the tool on
by default (only `experimental.image_generate: false` disables it). On
2.2.2+, the gallery lost every generation entry and the Design companion
fixture timed out; 2.2.1 passed.
- Images are implemented for the 2.2.3 contract only, with no fallback
to the old name: `IMAGE_TOOL` drives the gallery and its proof;
`imageGenerationSelection` reads unset as on; the Design agent and
skills name the new tool; the activation fixture exercises the image
tool instead of falling back to webfetch; the gallery fixture represents
the 2.2.3 transcript format.
- Older daemons (2.1.x, 2.2.1, 2.2.2) go through the existing
below-minimum path (`native_contract`). The 2.1.0 client/plugin/schema
pins stay.
- Help (all ten locales), READMEs, `CONTRIBUTING.md`, `dev-docs`
(compatibility, pruning, panel extensions, settings) and the
architecture skill describe the new minimum, its reason and default-on
image generation. The setup minimum-reason UI string is updated in all
locales.
## Contract review (v2.2.1 → v2.2.2 → v2.2.3; 40 + 101 commits)
Reviewed from the exact tags `v2.2.1` (`3ebcf9a32c`), `v2.2.2`
(`098aa7fd6e`) and `v2.2.3` (`082ac6281f`), the published npm packages,
and an authenticated OpenAPI dump from each official CLI running in its
own sandbox. The [changelog](https://opencode.ai/changelog) has entries
for both 2.2.2 (29 October, highlights only) and 2.2.3 (30 October, full
notes); everything below was also checked against the commit log and
source.
**Headline:** the HTTP contract CodeNomad consumes didn't change, but
2.2.2 **renamed the image tool** from `image_generate` to
`experimental_image_generate` and **turned it on by default**
([#60258](https://github.com/anomalyco/opencode/pull/60258)).
CodeNomad's Images/Design features match the old name and the old
default, so they break on 2.2.2 and later (see [Design companion
finding](#design-companion-finding)). Nothing else found affects
CodeNomad.
- **Authenticated OpenAPI:** **134 paths and 162 operations** on all
three, the same operation set. Schemas 355 → 350 → 351.
- **Added/removed operations:** none in either release.
- **Changed operations (2.2.2):** `GET /api/model`, `GET /api/event`,
`PUT /api/pty/{ptyID}`, `POST /api/shell`, `GET /api/shell/{id}/output`,
`POST /api/debug/heap-dump` and `GET /api/experimental/migration/v1`.
All of these are **representation-only**: the Effect 4.0.6 JSON Schema
output flattens nested `anyOf`, bounds integers with `maximum:
9007199254740991` (and `minimum` for signed integers), and rewrites the
numeric-string query pattern. The event-type and model-type enums are
unchanged.
- **Changed operations (2.2.3):** only the description of `POST
/api/credential`, which can now be refused by an `integration.connect`
policy.
- **Consumed schemas:** the same family selector as the 2.2.1 review
(`V2EventEncoded`, `Session.*`, `SessionStats.*`, `Form.*`,
`Permission.*`, `Prompt*`, `Event.*`, `Location.*`, PTY/Shell).
Re-derived from that description it selects 104 schemas at 2.2.1 (the
2.2.1 file says 103), all byte-identical from 2.1.4 to 2.2.1.
- In 2.2.2 the seven alias copies `Form.Fields_1..3` and
`Session.Message.Native_1..4` collapse into their base schemas, which
are byte-identical to the copies, leaving **97**. Of these, 71 are
byte-identical and 24 differ only in generator representation.
- Two changes are additive and optional: `Session.Info.time.busy`, the
start of the latest execution
([#59910](https://github.com/anomalyco/opencode/pull/59910)), and the
input field `PromptInput.FileAttachment.source` (`Prompt.FileSource`,
inline or uri; CodeNomad doesn't send it).
- `V2EventEncoded`, `Session.Message.*` content, `Session.Inbox.*`,
`Form.*` semantics, `Permission.*` and `Event.SeqEncoded` are unchanged.
- From 2.2.2 to 2.2.3 the family is byte-identical.
- **`Config.InfoEncoded`:** no semantic change in 2.2.2 (representation
only). 2.2.3 extends the managed-policy `action` enum (top-level and
`experimental.policies`) with `integration.connect`, `mcp.use`,
`skill.use` and `plugin.use`
([#60315](https://github.com/anomalyco/opencode/pull/60315)); CodeNomad
writes no policies. The *meaning* of `experimental.image_generate`
changed: unset now means on, and only `false` turns it off. The schema
shape stayed the same and the OpenAPI carries no description, so no
contract signal reveals it.
- **Schedules (not consumed on dev):** `when` becomes optional;
`if`/`until` conditions (shell in 2.2.2, Code Mode in 2.2.3) are added;
outcomes gain `checked`/`expired`.
- **Admission:** every predicate in `compatibility/negotiate.ts`
(unchanged since the 2.2.1 review) holds on 2.2.1, 2.2.2 and 2.2.3.
- **Instance proxy:** no new routes and an unchanged allowlist. Proxied
routes whose representation changed: `GET /api/model`, `PUT
/api/pty/{id}`, `POST /api/shell` and `GET /api/shell/{id}/output`.
Integer bounds and an equivalent numeric pattern accept everything
CodeNomad sends.
- **Published declarations** (2.2.1 → 2.2.3):
- **Client:** 185 methods on all three; the method tree is identical.
2.2.2 adds the generated types `ScheduleCondition*`; `FormFields2` is
renamed to `FormFields1`, which is generated-type churn. 2.2.3 adds the
Promise media helpers `withMediaRefs`, `mediaHashFromUri` and
`MediaRequestOptions`
([#60116](https://github.com/anomalyco/opencode/pull/60116)) and
persistent-PTY frame helpers in `solid/pty`. CodeNomad imports none of
these.
- **Schema:** 2.2.2 adds schedule conditions (`ShellCondition`,
`CheckMode`, …) and exports `SessionLegacy.part`. 2.2.3 adds
`CodeCondition*` and `policy.Action`.
- **Plugin:** 2.2.2 adds the GUI
`ComposerQuoteAnchor`/`ComposerFocusOptions`. 2.2.3 has no export
changes, but the optional peers `@opentui/*` become `>=0.8.0`
([#60385](https://github.com/anomalyco/opencode/pull/60385)). The
published `dependencies.effect` moves from **4.0.1 to 4.0.6** (2.2.2).
- **Typecheck:** the server and UI typecheck with **0 errors** against
the 2.2.2 and 2.2.3 client/schema/plugin/effect declarations through
scratch `paths` overrides. The pinned 2.1.0 control is also clean. The
harness now also remaps `effect` itself; the 2.2.1 harness skipped it
because effect's `exports` are plain `.js` strings.
- **Host modules:** the three daemon-loaded bundles still import
`@opencode/plugin` (`Plugin`), `/effect` (`Plugin`, `Rpc`, `Location`),
`/promise/adapter` (`fromPromise`), `/rpc` (`Rpc`), `effect` and
`effect/encoding` (`Base64Url`) from the host. A probe plugin in an
isolated **2.2.3** daemon resolves every module and binding, as on
2.2.1. `runtime-modules.ts` is unchanged between the tags.
- **Host Effect: 4.0.1 → 4.0.6** (2.2.2,
[#59630](https://github.com/anomalyco/opencode/pull/59630)). The 2.1.0
`@opencode/schema`/`@opencode/client` code bundled into the Missions and
pruning plugins now runs on host Effect 4.0.6. The plugin-runtime,
pruning, Missions-contract, permission-receipts and image-settings
native suites pass on 2.2.3.
- **Private native services:** the keys (`LocationServiceMap`, `Form`,
`Permission`, `Location`, `Job`, `Database`, `Session`, `Bus`) and the
members CodeNomad calls are unchanged. The changes are additive:
`Permission.Unattended` (a reference that denies unanswerable asks for
schedule checks), a `CorrectedError.message` getter, and `Session`
deciding fork media from the parent's location.
- **Storage** (three migrations): `session_part` (new table),
`session_v2.time_busy` and four `schedule` check columns.
- **`session_part`**
([#58915](https://github.com/anomalyco/opencode/pull/58915)): history
reads now *prefer* `session_part` rows over
`session_message.data.content` for assistant messages. The projector
writes parts there only for messages that already have part rows, so new
messages stay inline. Every 2.2.3 fixture DB inspected has **0**
`session_part` rows, and upstream `dev` (`1e28374e48`, 30 October) has
no writer either.
- The tables CodeNomad reads directly keep their shape.
- **Forward risk:** when a release starts writing parts, CodeNomad's
direct `session_message.data.content` readers and the pruning `UPDATE …
json_set(data,'$.content',…)` (`session-pruning/transaction.ts`) would
silently miss or be shadowed by part rows. See Recommendations.
- **Behavior changes checked:**
- **Image generation** (2.2.2): renamed and on by default. See the
[dedicated section](#design-companion-finding).
- **Code Mode:** inner tool progress no longer replaces the `execute`
call rows ([#60480](https://github.com/anomalyco/opencode/pull/60480)),
and progress is throttled to at most one update per 100 ms
([#60120](https://github.com/anomalyco/opencode/pull/60120)). Programs
see the same failure text as direct calls
([#60109](https://github.com/anomalyco/opencode/pull/60109)), `fetch` in
Code Mode is now subject to `webfetch` permissions
([#59954](https://github.com/anomalyco/opencode/pull/59954)), `for…in`
visits inherited keys
([#59933](https://github.com/anomalyco/opencode/pull/59933)) and `null`
survives text encoding
([#57639](https://github.com/anomalyco/opencode/pull/57639)). The
run-to-completion regression behind the 2.1.2 minimum passes on 2.2.3:
`{ total: 2000, beforeAwait: 1000, count: 1000 }`.
- **Permissions and MCP:** permission reasons and feedback are kept in
MCP tool failures
([#60102](https://github.com/anomalyco/opencode/pull/60102)). Shell
permission checks moved fully off tree-sitter and now check redirects,
PowerShell method calls and dynamic directory changes
([#60332](https://github.com/anomalyco/opencode/pull/60332),
[#60376](https://github.com/anomalyco/opencode/pull/60376)), so some
shell commands may now ask where they didn't. The managed-policy split
(`integration.use` vs `mcp.use`/`skill.use`/`plugin.use`) is a changelog
"breaking change" for managed deployments only.
- **Sessions:** deleting a session removes its persistent terminals
([#60322](https://github.com/anomalyco/opencode/pull/60322)), and a
persistent terminal with a missing cwd is rejected
([#60300](https://github.com/anomalyco/opencode/pull/60300)). Forked and
imported sessions store media as blobs when `media_blob` is on
([#60118](https://github.com/anomalyco/opencode/pull/60118)). The native
fork suite passes on 2.2.3.
- **Providers:** a built-in **Claude Agent** provider uses the user's
Claude Code login
([#58782](https://github.com/anomalyco/opencode/pull/58782)).
Plugin-supplied model variants are preserved
([#60097](https://github.com/anomalyco/opencode/pull/60097)), and the
dynamic provider npm fallback runs after external SDK hooks
([#60380](https://github.com/anomalyco/opencode/pull/60380)). These are
source-reviewed and touch no consumed contract.
- **Persistent PTY binary** (the process daemon): 2.2.2 switches from
`@opencode-ai/pty` 0.3.1 to `@opencode/pty` **0.3.3**
([#60276](https://github.com/anomalyco/opencode/pull/60276)).
`process-daemon-v0.3.3` contains only the release commit after 0.3.2 (a
version bump of the `@opencode/pty-*` binaries). **v0.4.0** (terminal
renaming, [#60324](https://github.com/anomalyco/opencode/pull/60324)) is
**not** shipped in CLI 2.2.3, which pins 0.3.3. CodeNomad only lists
persistent PTYs (worktree deletion guard), whose schema is unchanged
apart from representation.
- **Client fix not inherited:** the 2.2.3 client evicts missing sessions
on 404 ([#60459](https://github.com/anomalyco/opencode/pull/60459)).
CodeNomad stays on the 2.1.0 client.
- **`@opencode/ai` breaking changes** (media moved to `/experimental`,
one `tool()`): CodeNomad doesn't import `@opencode/ai`.
- Desktop/TUI-only changes (timeline performance, side-panel tabs,
spellcheck, question sounds, OpenTUI 0.8) don't affect CodeNomad.
**Verdict:**
- The **2.1.0 client/plugin pins stay**. Bumping them would bring
nothing CodeNomad consumes.
- No consumed HTTP/plugin contract broke; the breaking change is the
image tool contract of #60258, consumed by the Images gallery, the
Design agent and the Images settings.
- **Decision applied in this PR:** 2.2.3 becomes both the minimum and
the recommendation, and Images are implemented for the 2.2.3 contract
only (see Summary). This replaces the review's initial suggestion to
keep the 2.1.2 minimum and accept both tool names.
**Not verified here:**
- the full native suite matrix on 2.2.2/2.2.3; only the runs in Appendix
I were performed;
- the forward-compatibility of the `session_part` readers against a
runtime that writes parts (no such runtime exists yet);
- the Claude Agent provider and shell-permission changes at runtime
(source only);
- macOS/Linux.
---
## Design companion finding
**Symptom:** `scripts/test-design-companion-native.mjs <cli>` passes on
2.2.1 and fails on 2.2.2 and 2.2.3 with `Error: Timed out: series 1
generated and read`. Reproduced independently in a scratch checkout of
`origin/dev` (`f39642bc4`), with `CODENOMAD_NATIVE_FIXTURE_PARENT`
outside the home:
```
test-design-companion-native 2.2.1 exit=0 PASS AC-16, AC-52
test-design-companion-native 2.2.2 exit=1 Timed out: series 1 generated and read
test-design-companion-native 2.2.3 exit=1 Timed out: series 1 generated and read
```
**What the step waits for**
(`test-design-companion-native.mjs:238-241`): the fixture's loopback
chat provider answers a `RUN [...]` turn with two tool calls `{ tool:
"image_generate", args: { prompt, path: ".codenomad/design/icon/<name>"
} }`. The step then waits until the transcript holds two synthetic
notices with `metadata.source === "image_generate"` (line 209) and two
`read` parts of the generated files. No HTTP generate route, file watch
or media blob is involved; it is the agent tool path.
**Cause: an intentional upstream contract change, not an upstream bug.**
In 2.2.2, [#60258](https://github.com/anomalyco/opencode/pull/60258)
(`d4e48f54da`, "turn experimental_image_generate on by default") changed
`packages/core/src/tool/plugin/image-generate.ts`:
- `export const name = "image_generate"` →
`"experimental_image_generate"`. That one constant is the tool name, the
permission action (`assertions: ["experimental_image_generate", "edit",
"read"]`), the Job `type`, and the completion notice's
`metadata.source`. `session/execution/restart.ts` also tags
restart-recovery notices `source: "experimental_image_generate"`.
- The opt-in became default-on: `if (!enabled || imageGenerate(entries)
=== false) return`. An unset `experimental.image_generate` now offers
the tool; only `false` removes it ("still honored for configs from when
the tool was opt-in; permissions are the supported way to turn it off").
- The 2.2.2 changelog states it: "agents can now use
`experimental_image_generate` without additional configuration".
2.2.2 also wraps the notice text as `<image id="…"
state="…">\n…\n</image>` and adds `id` to the tool output
([#60098](https://github.com/anomalyco/opencode/pull/60098)).
CodeNomad's `Saved image: (.+) \(` parse still matches; `jobID`, `state`
and `path` metadata are unchanged.
**Evidence** (fixture DBs copied read-only to `evidence/`):
```
2.2.3, original fixture (calls "image_generate"):
seq 5 tool image_generate error "No tool named \"image_generate\" is currently available. Please use a tool from the available tool list." (x2)
-> no image job, no notice, no read: the wait times out.
2.2.3, fixture with the tool name changed (scratch copy; CodeNomad server code unmodified):
seq 5 tool experimental_image_generate completed {path:…/icon-minimal-a, model:"fiximg/image", jobID:"image_18cfb59…"}
seq 18 synthetic {"source":"experimental_image_generate","jobID":"image_18cfb59…","state":"completed",…}
<image id="image_18cfb59…" state="completed"> | Image request finished. Saved image: …
seq 20 tool read completed (x2) … seq 40/48/49 refinement
-> files, image calls and reads all correct, then
AssertionError: generations.length 0 !== 3 (test line 260: gallery "generation" entries)
```
So the product bug is real and independent of the fixture: on 2.2.2+
CodeNomad's Images gallery finds **no generation entries**. Images still
appear through their `read` parts, but without prompt, model, lineage or
"proven" origin, and `galleryImageReference` refuses them as `changed`.
**CodeNomad code that assumes the 2.2.1 name or default** (origin/dev):
| Where | Assumption | Effect on 2.2.2+ |
| --- | --- | --- |
| `session-pruning/assets-gallery.ts:56,139` | `part.name ===
"image_generate"` | no generation entries; references refused `changed`
|
| `session-pruning/assets-gallery-proof.ts:104,130` | tool name and
notice `source === "image_generate"` | no calls or notices, so no
provenance proof |
| `opencode/image-settings.ts` `imageGenerationSelection(undefined) →
false` (doc: "Reads … as OpenCode does") | unset means off | Settings →
Images shows **Off** and `images.status()` returns `"disabled"` while
the tool is offered; help step "Turn on image generation"
(`docs/help/en/extensions.md:73`) is no longer needed |
| `opencode/design/opencode/agents/design.md`, `skills/design-core`,
`design-logo`, `design-ui-mockup` | the agent is told to call
`image_generate` | the model sees only `experimental_image_generate`;
the first call can fail with "No tool named …" |
| `scripts/test-design-companion-native.mjs:125,209,238,301` | fixture
calls/filters `image_generate` | red on 2.2.2+ |
| `scripts/test-design-activation-native.mjs:76,307` | ask rule on
action `image_generate`; tool detection by that name | **passes but
loses coverage**: `askTool` falls back to `webfetch` on 2.2.2/2.2.3
(logged) |
| `dev-docs/SESSION_PRUNING_RPC.md`, `PANEL_EXTENSIONS.md`,
`SETTINGS.md` | describe `image_generate` parts and opt-in | out of date
for 2.2.2+ |
User permission rules written for action `image_generate` no longer
match on 2.2.2+; that is an OpenCode-side change for users. CodeNomad's
help never names the permission action; the Design fixtures and agent
use `experimental_image_generate`.
**Fix in this PR** (2.2.3 contract only, no fallback):
1. One `IMAGE_TOOL = "experimental_image_generate"` constant drives the
gallery and its proof; the gallery reads the 2.2.3 notice format.
2. The native fixtures use the new tool; the activation fixture
exercises it (default on) instead of falling back to webfetch.
3. The Design agent and skills name `experimental_image_generate`.
4. `imageGenerationSelection` reads an unset
`experimental.image_generate` as on; only `false` disables it. Settings
→ Images and `images.status()` report it that way.
## Follow-up
- Hardening for `session_part` (independent of this upgrade, no 2.2.3
regression): make the direct readers and the pruning transaction fail
safe when `session_part` has rows for the target messages.
## Isolated Windows qualification
Base: dev `f39642bc4`; Node 25.2.1 (local; CI runs the pinned 24.20.0);
exact official CLI **2.2.3**; locked client/plugin **2.1.0**;
`CODENOMAD_NATIVE_FIXTURE_PARENT` outside the user profile for the
Design fixtures.
- **Before the image fix (recommendation-only change):** every native
suite passed on 2.2.3 except the Design companion end to end, which
passes on 2.2.1 and times out on 2.2.2/2.2.3 at "series 1 generated and
read" (`No tool named "image_generate" is currently available`).
- **After this change, on 2.2.3:** Design companion (3 files, 2 series,
all proven, lineage), Design activation (image tool offered to Design
and Build, default on), Design content, image settings (default on,
Off→On hot reload), session pruning including session images/media, Code
Mode jobs `{ total: 2000, beforeAwait: 1000, count: 1000 }`.
- **Full native set on 2.2.3 (before the image fix, unaffected areas):**
plugin runtime, automation, Location/worktrees/event relay, permission
receipts, Git init/degraded, Missions (contract, family control, native,
trajectory) and all 11 recurring journeys, sessions (environment, fork,
aside, interrupt, lifecycle, blank cleanup, compaction, prompt skills,
providers, service usage, web search, plugin packages, output limit,
Promise-tool failure, subagent depth, temporary workspaces), migrations
from 2.1.2/2.2.1/2.2.2, install/upgrade/legacy replacement.
- **Units and checks after the change:** root and server typecheck
clean; server **2,825 passed, 9 skipped, 1 cancelled** (`index.test.ts`
shutdown test timed out under full-suite load; **4/4** alone); gallery
107/107; Design 23/23; opencode-update 62 passed / 1 skipped; touched UI
units 8/8; browser `opencode-setup` + `websearch-settings` 38/38; native
plugin build 2/2; ten-locale help 31/31.
12 KiB
12 KiB
面板扩展
浏览已安装和在线扩展
- 在右侧面板标签栏中打开自定义右侧面板。
- 展开分隔线下方的扩展。
- 使用搜索扩展搜索已安装附加组件和官方在线目录组成的单一列表。悬停或聚焦条目查看元数据。
每次打开自定义弹出框时，折叠区域都默认关闭。已安装和在线条目按扩展 ID 合并；没有单独的管理窗口或已安装/在线模式。浏览目录元数据不会下载或执行作者的面板代码。目录维护于 CodeNomad Extensions；收录及声明的作者姓名并非签名或信任证明。
目录不可用时，已安装扩展和**从 ZIP 安装…**仍可使用。刷新可重试发现。折叠或关闭弹出框会放弃待处理检查/确认界面；不会静默安装任何内容。
检查并安装但不启用
- 在目录条目上选择安装…，或对另行获得的软件包选择从 ZIP 安装…。
- 检查软件包 ID、作者、仓库、版本、API/权限和 SHA-256 摘要。需要时展开技术详情。
- 验证发布者，并在可用时通过可信渠道比较摘要。
- 只有信任代码时，才选择我信任此软件包及其作者，然后选择安装但不启用。
检查会下载/重新验证所选软件包；不会执行作者代码。摘要标识精确字节，而非作者身份。目录软件包来自精确声明的 GitHub 发行版资源，而非任意 URL。手动软件包是仅包含 manifest.json 和自包含 panel.html 的 ZIP；无效或不受支持的软件包会被拒绝。
安装无需重启 OpenCode，且绝不自动授予激活权限。验证失败、冲突或存储操作失败不意味着允许以不同字节重试。新一次安装尝试前请重新检查软件包。
激活并了解范围
- 返回自定义右侧面板中扩展折叠区域上方的附加组件行。已安装但禁用的组件仍在该列表中。
- 勾选复选框激活。取消同一复选框即可禁用。
该复选框是唯一激活控件：没有额外管理器开关或按窗口的可见性开关。激活作用于整个配置下的所有项目，而非按文件夹生效。远程连接时，它影响服务器已安装扩展存储，而非仅影响查看设备。
扩展存储是所选 CodeNomad 配置旁的 panel-extensions/。如果不同桌面数据配置文件使用同一配置目录，它们不会隔离扩展。反过来，打开不同配置也不代表获准运行安装在其他位置的附加组件。区别请参阅桌面窗口与数据。
启用的面板可在选中时挂载；隐藏可能清除其临时界面状态。禁用会撤销激活。自定义中的重置只恢复内置布局，不会启用、禁用或卸载扩展。
替换或移除
- 使用更换版本…，或检查同 ID 的另一个 ZIP，替换已安装软件包。
- 检查新摘要和权限，确认信任，然后安装但不启用。
- 只有决定信任替换版本后，才通过普通复选框重新激活。
- 卸载时，检查目标后使用移除…和确认移除。
每次替换都会撤销所有项目中的激活，即使权限列表未变，并清除面板自身已保存的设置。验证/冲突/存储失败会保留已安装软件包。扩展不会静默更新。移除会删除软件包、其激活设置及已保存的面板设置，而非 OpenCode 会话或项目文件。出现不想要的代码时，先禁用；只重新安装已验证可信的软件包。
上下文、资源同意和沙箱限制
| 契约 | 激活允许的内容 |
|---|---|
API 1 / session.context |
当前会话标识符（或无）、界面语言和外观。无对话文本或文件系统访问。 |
API 2 / session.assets.read 加上下文 |
显式审查过的权限，用于列出有界的当前会话工具结果图片/附件元数据，并读取受支持的嵌入字节。不提供通用对话、文件或 URL 访问。 |
API 3 / repository.workItems.read 及上下文 |
经明确审查的权限：分页列出项目仓库在 GitHub、GitLab 或 Gitea/Forgejo 上的 issue 和 pull request（页数有上限），并在浏览器中打开其中一项。这不是文件、凭据或一般网络访问。 |
| API 4 / 上下文加以下一项或多项权限 | 审查时每项声明的权限显示一句说明；激活会一并授予全部权限，替换会全部撤销。 |
session.images.read |
读取所显示对话中 read 工具返回的图像，并在可验证时附带生成状态和来源谱系。 |
session.images.prompts（需要 session.images.read） |
读取项目“图像”对话中生成的每张图像的提示词和模型。 |
composer.prefill |
向所显示对话的输入框添加文本。绝不会发送消息。 |
images.conversation |
打开或开始此项目的“图像”对话。 |
opencode.designAgent |
在此扩展启用期间，将 CodeNomad 的 Design 智能体及其图像技能添加到 OpenCode。 |
panel.preferences |
记住此面板自身的设置。 |
资源访问跟随当前挂载的宿主/会话，而非作者选择的会话。本地/远程引用可能列为不可用；资源 API 不获取任意远程 URL 或打开本地文件。切换会话、断开连接或撤销同意会使旧访问失效。
在 API 4 中，图像读取同样跟随所显示的对话，且只显示智能体读回该对话的图像。拥有 session.images.prompts 的扩展可以读取您或智能体在“图像”对话中为图像编写的提示词，并且尽管有沙箱，仍可能将其转交他人，因此只应授予您愿意托付这些内容的作者。由 composer.prefill 添加的文本会留在输入框中，直到您编辑它或选择发送消息；它绝不会以命令开头，绝不会以未完成的 @ 提及结尾，并以纯文本引用图像路径。在输入框中用 Ctrl+Z（macOS 上为 Cmd+Z）撤销不会移除它。已保存的面板设置属于此 CodeNomad 配置，每个扩展最多 4 KiB；禁用扩展会保留它们。
这些条目来自项目文件夹的 upstream 远程仓库，否则来自 origin。CodeNomad 使用您已登录的 GitHub、GitLab 或 Gitea CLI（gh、glab、tea）读取它们，公开仓库可匿名读取，且不存储任何令牌；扩展只能看到仓库名称和条目。匿名读取仅适用于 github.com、gitlab.com、codeberg.org 和 gitea.com；自托管平台只能通过已登录该平台的 CLI 读取。打开条目时，CodeNomad 会在浏览器中打开该条目在同一平台上的页面，每秒最多一次；扩展无法打开其他地址。
作者代码在受限 iframe 中运行，而非可信应用渲染器。它无法获得原生/OpenCode 桥接、凭据访问、通用 RPC、表单、弹出窗口或下载；网络 API 和外部资源受限。扩展是界面附加组件，而非 OpenCode 插件。
沙箱不是进程/CPU 隔离，也不保证获批代码无害。恶意扩展可能干扰其渲染器。只安装可信作者的扩展，不提供秘密，行为异常时禁用/移除组件。
使用 Design 扩展创建图像
Design 扩展是一个看片台，用于查看你在项目的图像对话中与 CodeNomad 的 Design 智能体一起创建的图像。它显示图像、在消息框中准备请求，而每次生成都由你发送的消息触发。
- 连接一个提供图像模型的提供商。除非已在设置 → 提供商 → 图像中关闭，图像生成默认开启（图像生成与存储）。
- 在自定义右侧面板 → 扩展中，先审查它的权限（上下文、资源同意和沙箱限制），再从目录安装 Design（检查并安装但不启用），然后勾选它的复选框（激活并了解范围）。
- 打开 Design 面板，选择打开图像对话。
扩展启用期间，CodeNomad 会将它的 Design 智能体及图像技能添加到 OpenCode。你自己的 design 智能体和你自己的 design-* 技能始终优先；当你提供自己的 design 智能体时，面板显示**正在使用你自己的 Design 代理。**缺少图像生成、图像模型或 Design 智能体时，面板也会说明。
图像对话
每个项目文件夹或 worktree 都有自己的图像对话，标题为图像。打开图像对话会找到它，或使用 Design 智能体以及 CodeNomad 为该智能体的新对话选择的模型创建它，然后显示该对话并将焦点放在消息框中；打开不会发送任何内容。已有的图像对话保留自己的模型。新建图像对话会以空的看片台开始另一个对话；当一个对话包含大量图像时，面板会建议这样做，之后打开会显示最新的对话。已归档和已删除的图像对话会被跳过。
描述你的需要并发送：智能体会问几个确定方向的问题，说明将生成几张图像，生成它们，再逐张读回并评估。图像保存在项目文件夹的 .codenomad/design/ 中。CodeNomad 会将该文件夹加入仓库的本地 Git 排除规则（.git/info/exclude），不改动 .gitignore；无法加入时，面板显示**此位置的图像可能会出现在 Git 中。**撤销一轮会把它的图像从看片台移除，但保留文件；被智能体覆盖的图像无法恢复。智能体请求约 1K 像素的图像，但提供商可能返回更大的图像，同时生成多张大图可能占用共享 OpenCode 服务的大量内存。
如果使用 Design 智能体的图像对话中缺少该智能体，消息框会显示Design 智能体不可用并阻止发送：选择使用默认智能体，或重新启用 Design 扩展。如果对话的聊天模型无法接收图像，面板会提示智能体无法从视觉上评估它们；它读回的图像仍会显示在看片台上。
看片台
看片台显示智能体在当前对话中读回的图像，从新到旧，按回复分组。选中图像会放大显示，并在小尺寸中提供 16、32 和 64 px 预览；比较将两张图像并排放置，查看原图打开查看器。面板较窄时，请加宽后再比较。谱系（生成自、用于）以及图像对话中的提示词和模型，仅在 CodeNomad 能验证图像由哪次生成产生时显示；否则图像保留像素并标记为来源无法验证。生成记录列出每次图像生成及其状态；请在对话中跟进进度。在其他对话中，面板显示该对话中读回的图像，不含提示词和请求，并提供打开图像对话的入口。
在图像对话中，从模板开始（例如应用图标或标志等方案）、优化、变体、应用方向、保存到项目…、请代理显示它和重试只会在消息框中添加可编辑的文本：面板从不发送消息，也从不生成图像。针对所选图像的操作会以相对于项目的路径引用该图像，且只能引用来源可验证的项目图像。编辑请求后由你自己发送。**保存到项目…**会请智能体把图像复制到你在请求后输入的目标位置。每轮图像数（1 到 4，默认 3）会包含在生成新图像的请求中，并保存在面板的已存设置里。在手机上，面板以浮动方式显示，添加请求后会关闭。
不使用 CodeNomad 时使用 Design 智能体
Design 智能体及其技能是普通的 OpenCode 文件。要在没有 CodeNomad 的情况下于 OpenCode TUI 或其他客户端中使用，请将 Design 内容文件夹中的内容复制到项目的 .opencode/ 文件夹或全局 OpenCode 配置文件夹（~/.config/opencode/），并将 NOTICE.md 和许可证一同保留。然后选择 design 智能体；它按名称加载自己的技能，其他智能体只有在你点名时才会使用这些技能。
Design 智能体及其技能改编了 Open Design（Apache-2.0）和 taste-skill（MIT）的材料；NOTICE.md 列出了每个改编的文件。Design 扩展复用了 MCP Assets 扩展的代码（MIT）。