@deveco-test/deveco-code 1.0.3 → 1.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (62) hide show
  1. package/CHANGELOG.md +13 -0
  2. package/package.json +6 -5
  3. package/resources/deveco/skills/customize-deveco/.deveco-builtin +1 -0
  4. package/resources/deveco/skills/customize-deveco/SKILL.md +469 -0
  5. package/resources/deveco/skills/deveco-cli/.deveco-builtin +1 -0
  6. package/resources/deveco/skills/deveco-cli/SKILL.md +240 -0
  7. package/resources/deveco/skills/hmos-arkui-develop-skill/.deveco-builtin +1 -0
  8. package/resources/deveco/skills/hmos-arkui-develop-skill/SKILL.md +83 -0
  9. package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-apis/01-layout.md +629 -0
  10. package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-apis/02-basic-components.md +645 -0
  11. package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-apis/03-data-display.md +81 -0
  12. package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-apis/04-selectors.md +76 -0
  13. package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-apis/05-media.md +60 -0
  14. package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-apis/06-advanced.md +32 -0
  15. package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-apis/07-security.md +30 -0
  16. package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-apis/08-state-decorators.md +79 -0
  17. package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-apis/09-animation.md +111 -0
  18. package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-apis/10-gesture.md +59 -0
  19. package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-apis/11-dialog-menu.md +92 -0
  20. package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-apis/12-navigation.md +81 -0
  21. package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-apis/13-rendering.md +22 -0
  22. package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-apis/14-extension.md +22 -0
  23. package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-apis/15-theme-style.md +10 -0
  24. package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-apis/16-enums.md +87 -0
  25. package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-apis/17-resources.md +1379 -0
  26. package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-apis/18-error-code.md +24 -0
  27. package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-apis/_index.md +75 -0
  28. package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-rules/00-arkts-syntax.md +229 -0
  29. package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-rules/01-import.md +116 -0
  30. package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-rules/02-uicontext.md +56 -0
  31. package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-rules/03-component.md +105 -0
  32. package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-rules/04-build.md +41 -0
  33. package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-rules/05-state.md +300 -0
  34. package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-rules/06-rendering.md +67 -0
  35. package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-rules/07-attribute-params.md +219 -0
  36. package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-rules/08-navigation.md +102 -0
  37. package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-rules/09-dialog.md +72 -0
  38. package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-rules/10-style.md +90 -0
  39. package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-rules/11-extension.md +54 -0
  40. package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-rules/12-layout.md +69 -0
  41. package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-rules/13-performance.md +27 -0
  42. package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-rules/14-deprecated.md +28 -0
  43. package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-rules/_index.md +79 -0
  44. package/resources/deveco/skills/hmos-runtime-fix-skill/.deveco-builtin +1 -0
  45. package/resources/deveco/skills/hmos-runtime-fix-skill/SKILL.md +187 -0
  46. package/resources/deveco/skills/hmos-runtime-fix-skill/SKILL_CN.md +160 -0
  47. package/resources/deveco/skills/hmos-runtime-fix-skill/evals/evals.json +17 -0
  48. package/resources/deveco/skills/hmos-runtime-fix-skill/reference/businesserror_patterns.md +17 -0
  49. package/resources/deveco/skills/hmos-runtime-fix-skill/reference/error_patterns.md +31 -0
  50. package/resources/deveco/skills/hmos-runtime-fix-skill/reference/fault-mode-library.md +57 -0
  51. package/resources/deveco/skills/hmos-runtime-fix-skill/reference/outofmemoryerror_patterns.md +19 -0
  52. package/resources/deveco/skills/hmos-runtime-fix-skill/reference/rangeerror_patterns.md +15 -0
  53. package/resources/deveco/skills/hmos-runtime-fix-skill/reference/referenceerror_patterns.md +23 -0
  54. package/resources/deveco/skills/hmos-runtime-fix-skill/reference/syntaxerror_patterns.md +14 -0
  55. package/resources/deveco/skills/hmos-runtime-fix-skill/reference/typeerror_patterns.md +19 -0
  56. package/resources/deveco/skills/hmos-runtime-fix-skill/reference/urierror_patterns.md +17 -0
  57. package/resources/deveco/skills/hmos-runtime-fix-skill/scripts/collect-hilog.mjs +120 -0
  58. package/resources/deveco/skills/hmos-runtime-fix-skill/scripts/jscrash-report.mjs +138 -0
  59. package/resources/deveco/skills/hmos-runtime-fix-skill/scripts/parse-jscrash-log.mjs +126 -0
  60. package/resources/deveco/skills/hmos-runtime-fix-skill/scripts/shared/deveco-cli.mjs +79 -0
  61. package/resources/deveco/skills/hmos-runtime-fix-skill/scripts/shared/jscrash-parse.mjs +389 -0
  62. package/resources/deveco/skills/hmos-runtime-fix-skill/scripts/shared/utils.mjs +27 -0
package/CHANGELOG.md CHANGED
@@ -1,5 +1,18 @@
1
1
  # Changelog
2
2
 
3
+ ## v1.0.4 (2026-10-13)
4
+
5
+ ### DevEco Code 核心
6
+
7
+ #### 优化
8
+
9
+ - 内置技能改为原生注册:随安装包发行,不再在启动时解压到 `~/.config/deveco/skills`,并在启动时自动清理历史解压副本(含 v1 遗留的 `~/.local/share/deveco/skills`),用户自建技能不受影响
10
+ - 产品定制指南 `customize-deveco` 基于 V2 全面重写:离线自足,覆盖双配置平面(`deveco.json` / `cli.json`)、热加载语义、插件 v2 API、CLI/服务/日志排障,并附上游文档翻译表;移除面向上游项目的 opencode/report 内置技能
11
+
12
+ #### 缺陷修复
13
+
14
+ - 修复安装版 `deveco -v` 显示的版本与 npm 包版本不一致的问题(本版起二进制内嵌真实发布版本号)
15
+
3
16
  ## v0.1.9 (2026-08-20)
4
17
 
5
18
  ### DevEco Code 核心
package/package.json CHANGED
@@ -6,7 +6,7 @@
6
6
  "scripts": {
7
7
  "postinstall": "node ./postinstall.mjs"
8
8
  },
9
- "version": "1.0.3",
9
+ "version": "1.0.4",
10
10
  "license": "MIT",
11
11
  "os": [
12
12
  "darwin",
@@ -20,16 +20,17 @@
20
20
  ],
21
21
  "files": [
22
22
  "bin/**/*",
23
+ "resources/**/*",
23
24
  "postinstall.mjs",
24
25
  "LICENSE",
25
26
  "README.md",
26
27
  "CHANGELOG.md"
27
28
  ],
28
29
  "optionalDependencies": {
29
- "@deveco-test/deveco-code-windows-x64": "1.0.3",
30
- "@deveco-test/deveco-code-darwin-x64": "1.0.3",
31
- "@deveco-test/deveco-code-darwin-arm64": "1.0.3",
32
- "@deveco-test/deveco-code-openharmony-arm64": "1.0.3"
30
+ "@deveco-test/deveco-code-windows-x64": "1.0.4",
31
+ "@deveco-test/deveco-code-darwin-x64": "1.0.4",
32
+ "@deveco-test/deveco-code-darwin-arm64": "1.0.4",
33
+ "@deveco-test/deveco-code-openharmony-arm64": "1.0.4"
33
34
  },
34
35
  "dependencies": {
35
36
  "@deveco/deveco-cli": "1.3.4"
@@ -0,0 +1 @@
1
+ customize-deveco
@@ -0,0 +1,469 @@
1
+ ---
2
+ name: customize-deveco
3
+ description: "Use for any question about DevEco Code itself: configuration (deveco.json, deveco.jsonc, cli.json), customization, agents, commands, skills, plugins, MCP servers, permissions, themes, keybinds, CLI and TUI behavior, the background service, logs, and troubleshooting. Also use when creating or editing files under .deveco/ or ~/.config/deveco/. Do not use for the user's own application code, or for any project that is not configuring DevEco Code itself."
4
+ ---
5
+
6
+ # Customizing DevEco Code
7
+
8
+ This guide is self-contained and grounded in the shipping v2 codebase — prefer
9
+ it over memory or web search. Upstream V2 documentation links (with the
10
+ OpenCode→DevEco translation table) are collected at the end for deep dives
11
+ when the network is reachable.
12
+
13
+ ## Two configuration planes
14
+
15
+ DevEco Code is a client-server product; configuration is split accordingly.
16
+ Do not mix the two files:
17
+
18
+ | Plane | File | Owns |
19
+ | --- | --- | --- |
20
+ | Server / project config | `deveco.json` or `deveco.jsonc` (JSONC, trailing commas allowed) | agents, commands, skills, plugins, MCP, permissions, providers, models, instructions, references, formatter, LSP |
21
+ | CLI / TUI preferences | `~/.config/deveco/cli.json` (global only, no project-local form) | theme, keybinds, leader timeout, scroll, diffs, tabs, notifications/sounds, terminal, `debug.devtools` |
22
+
23
+ `cli.json` accepts `"$schema": "https://opencode.ai/v2/cli.json"` for editor
24
+ validation. The server config has **no** published v2 schema URL: the
25
+ well-known `https://opencode.ai/config.json` describes **V1** — never infer v2
26
+ field names or shapes from it.
27
+
28
+ A third surface, the TUI storage channel (`~/.local/state/deveco/<channel>/tui/`),
29
+ persists client-local state (tabs, caches). It is not user configuration.
30
+
31
+ ## Where files live
32
+
33
+ | Scope | Path |
34
+ | --- | --- |
35
+ | Global config dir | `~/.config/deveco/` (`$XDG_CONFIG_HOME/deveco` when set) |
36
+ | Global server config | `~/.config/deveco/deveco.json(c)` |
37
+ | Global CLI/TUI config | `~/.config/deveco/cli.json` |
38
+ | Global agents / commands / skills / plugins | `~/.config/deveco/{agent,agents,mode,modes}/`, `{command,commands}/`, `{skill,skills}/`, `{plugin,plugins}/` |
39
+ | Global themes | `~/.config/deveco/themes/<name>.json` |
40
+ | Global instructions | `~/.config/deveco/AGENTS.md` |
41
+ | Project config | `./deveco.json(c)` or `./.deveco/deveco.json(c)` in **any** directory (walk-up goes to the filesystem root, so monorepo packages and parent dirs all count) |
42
+ | Project surfaces | `.deveco/{agent,agents,mode,modes,command,commands,skill,skills,plugin,plugins,themes}/` |
43
+ | Project instructions | `AGENTS.md` (walked up from cwd to the project root) |
44
+ | Data (logs, db, specs) | `~/.local/share/deveco/` — `log/deveco.log`, `opencode.db`, `specs/` |
45
+ | State (service registration) | `~/.local/state/deveco/service.json` |
46
+ | Cache | `~/.cache/deveco/` (npm plugin installs under `npm/`, URL skill caches under `skills/`) |
47
+ | Cross-tool compatibility | `~/.claude/skills/` and `~/.agents/skills/` are auto-loaded as skill sources |
48
+
49
+ `deveco debug paths` prints every resolved path.
50
+
51
+ ## Discovery, merge, and hot reload
52
+
53
+ Config discovery walks from the session's working directory **up to the
54
+ filesystem root**. Each directory contributes its `deveco.json(c)` file and,
55
+ if present, its `.deveco/` directory. Merge precedence, lowest to highest:
56
+
57
+ 1. Global config dir documents
58
+ 2. An explicit file (`DEVECO_CONFIG=/path/to/file.json`)
59
+ 3. Direct `deveco.json(c)` files, farthest ancestor → cwd (nearer wins)
60
+ 4. `.deveco/` directory documents, farthest → cwd — **every discovered
61
+ `.deveco` config overrides every direct `deveco.json(c)`**
62
+ 5. Inline `DEVECO_CONFIG_CONTENT` JSON
63
+
64
+ Parsing is forgiving: unknown top-level keys are silently ignored; a document
65
+ that fails to parse is dropped with a log warning instead of blocking startup.
66
+ Legacy v1 keys are auto-migrated with diagnostics (`agent`→`agents`,
67
+ `permission`→`permissions`, `plugin`→`plugins`, flat `mcp.<name>`→`mcp.servers`,
68
+ `tools:{name:bool}`→permission rules, action renames `bash`→`shell`,
69
+ `task`→`subagent`, `write`/`patch`→`edit`); `logLevel`, `server`,
70
+ `subagent_depth`, `layout` are dropped as unsupported. String values support
71
+ `{env:VAR}` and `{file:path}` substitution (`{file:}` resolves relative to the
72
+ declaring config file, `~/` expanded).
73
+
74
+ **Config is hot-reloaded.** File watchers feed a debounced `config.updated`
75
+ event; agents, commands, skills, MCP servers, providers, formatters,
76
+ references, plugins and the remaining surfaces rescan live. After saving a
77
+ config change, no restart is needed — at most run `deveco reload`. Restart
78
+ (`deveco service restart`) is only required for changes fixed at server start:
79
+ `DEVECO_CONFIG*` env options, XDG/global path changes, and service settings
80
+ (hostname/port/password in `~/.config/deveco/service.json`).
81
+
82
+ ## deveco.json field guide (v2 native shapes)
83
+
84
+ Every field is optional.
85
+
86
+ ```jsonc
87
+ {
88
+ // Model selection: "provider/model" or "provider/model#variant"
89
+ "model": "deveco/glm-5.3",
90
+ "default_agent": "build",
91
+
92
+ // Agents keyed by name (files under .deveco/agent(s)/ preferred for prompts)
93
+ "agents": {
94
+ "harmony-build": {
95
+ "description": "Primary HarmonyOS build and delivery agent",
96
+ "mode": "primary",
97
+ "color": "#4DA3FF",
98
+ "steps": 100
99
+ }
100
+ },
101
+
102
+ // Commands keyed by name (files under .deveco/command(s)/ preferred)
103
+ "commands": {
104
+ "deploy": {
105
+ "template": "Deploy $ARGUMENTS to the connected device",
106
+ "description": "Deploy a hap",
107
+ "agent": "build",
108
+ "subagent": false
109
+ }
110
+ },
111
+
112
+ // Permissions: flat rule array, LAST matching rule wins
113
+ "permissions": [
114
+ { "action": "edit", "resource": "packages/migration/*", "effect": "deny" },
115
+ { "action": "shell", "resource": "git *", "effect": "allow" },
116
+ { "action": "shell", "resource": "rm *", "effect": "deny" }
117
+ ],
118
+
119
+ // MCP servers nested under mcp.servers
120
+ "mcp": {
121
+ "timeout": { "startup": 5000 },
122
+ "servers": {
123
+ "deveco-mcp-server": { "type": "local", "command": ["deveco-mcp-server"] },
124
+ "github": {
125
+ "type": "remote",
126
+ "url": "https://api.githubcopilot.com/mcp/",
127
+ "headers": { "Authorization": "Bearer {env:GITHUB_TOKEN}" }
128
+ }
129
+ }
130
+ },
131
+
132
+ // Extra skill sources: directory paths or http(s) URLs (plain string array)
133
+ "skills": [".deveco/team-skills", "https://example.com/.well-known/skills/"],
134
+
135
+ // Plugins: npm/git specs, {package, options}, local paths; "-<target>" removes
136
+ "plugins": ["deveco-gemini-auth", ["deveco-bar", { "key": "val" }], "-some-plugin"],
137
+
138
+ // Named references for @ autocomplete
139
+ "references": {
140
+ "docs": { "path": "../product-docs", "description": "Product docs" },
141
+ "effect": { "repository": "Effect-TS/effect", "description": "Effect v4 details" }
142
+ },
143
+
144
+ // Provider/model catalog overrides
145
+ "providers": {
146
+ "my-provider": {
147
+ "name": "My Provider",
148
+ "models": { "my-model": { "name": "My Model" } }
149
+ }
150
+ },
151
+
152
+ // Misc
153
+ "instructions": ["kb/arkts-guidelines.md"],
154
+ "formatter": false,
155
+ "lsp": true,
156
+ "snapshots": true,
157
+ "watcher": { "ignore": ["**/dist/**"] },
158
+ "media": { "image": { "auto_resize": true } },
159
+ "tool_output": { "max_lines": 200, "max_bytes": 8192 },
160
+ "compaction": { "auto": true },
161
+ "websearch": false,
162
+ "worktree": { "directory": "~/.local/share/deveco/worktrees" },
163
+ "share": "disabled",
164
+ "update": "notify",
165
+ "username": "string",
166
+ "shell": "/bin/zsh"
167
+ }
168
+ ```
169
+
170
+ Shape notes:
171
+
172
+ - `permissions` is a v2 **rule array** `{action, resource, effect}` with
173
+ wildcard matching; the v1 object form still loads via migration.
174
+ - `skills` is a **string array** of paths/URLs — not the v1 `{paths, urls}`
175
+ object.
176
+ - `mcp.servers[name]` is discriminated by `type` (`"local"` needs `command:
177
+ string[]`; `"remote"` needs `url`). Disable with `"disabled": true` (v1's
178
+ `enabled` is inverted during migration). OAuth settings are snake_case:
179
+ `client_id`, `client_secret`, `scope`, `callback_port`, `redirect_uri`,
180
+ `auth_server_metadata_url`.
181
+ - `plugins` entries: bare npm/git specifiers install into the cache; relative
182
+ paths resolve against the declaring config file; absolute paths must be
183
+ **directories**; a leading `-` removes a plugin (auto-discovered or built-in)
184
+ by target or id.
185
+ - `instructions` is declared in the schema but **not wired** in this baseline —
186
+ use `AGENTS.md` files for ambient instructions.
187
+
188
+ ## Agents
189
+
190
+ Two definition forms. Use files for anything with a real prompt.
191
+
192
+ **File form** — `.deveco/agent/<name>.md` or `.deveco/agents/<name>.md`
193
+ (subagents); `.deveco/mode/<name>.md` or `.deveco/modes/<name>.md` (primary
194
+ agents). Nested paths create namespaced names. Frontmatter fields (v2):
195
+ `model, request, system, description, mode ("primary"|"subagent"|"all"),
196
+ hidden, color (#rrggbb), steps, disabled, permissions`. The markdown **body**
197
+ becomes the agent's system prompt. Legacy v1 frontmatter (`tools`,
198
+ `permission`, `disable`, `temperature`, …) is migrated with diagnostics.
199
+
200
+ ```markdown
201
+ ---
202
+ mode: primary
203
+ model: deveco/glm-5.3
204
+ color: "#44BA81"
205
+ permissions:
206
+ - { action: "shell", resource: "*", effect: "ask" }
207
+ ---
208
+
209
+ You are a GitHub issue triage specialist...
210
+ ```
211
+
212
+ **Inline form** — the `agents` record in `deveco.json` (same fields; `system`
213
+ carries the prompt). Disable a built-in with
214
+ `"agents": { "build": { "disabled": true } }`. `default_agent` must name a
215
+ non-hidden primary agent.
216
+
217
+ ### Built-in agents
218
+
219
+ | Agent ID | Mode | Hidden | Description |
220
+ | --- | --- | --- | --- |
221
+ | `build` | primary | no | Default agent; DevEco system prompt, full tool access |
222
+ | `goal` | primary | no | Multi-turn goal-driven agent with verifiable termination |
223
+ | `plan` | primary | no | Plan mode; edit tools denied |
224
+ | `debug` | primary | yes | Sticky ArkTS debugging mode |
225
+ | `general` | subagent | no | General-purpose research and parallel tasks |
226
+ | `explore` | subagent | no | Fast read-only codebase search |
227
+ | `spec-implementation` | subagent | yes | Execute tasks from an approved spec |
228
+ | `spec-verify` | subagent | yes | Build, deploy, and UI-verify Harmony features |
229
+ | `compaction` / `title` / `summary` | internal | yes | Context summarization, thread titles, summaries |
230
+
231
+ Notable permission wiring: `build` asks for `verify_ui`,
232
+ `save_ui_screenshot`, `get_ui_verification_log`; `goal` allows `spec_write`;
233
+ `plan` denies all edits; `explore` is read-only; `debug` allows `debug_exit`
234
+ and drives builds/logs through `devecocli` in the shell.
235
+
236
+ ## Commands
237
+
238
+ `.deveco/command/<name>.md` or `.deveco/commands/<name>.md` (nested paths
239
+ namespace the name). The body is the prompt template; frontmatter accepts
240
+ `description`, `agent`, `model`, `subagent` (`subtask` is a deprecated alias).
241
+ In the template, `$ARGUMENTS` expands to everything typed after the command,
242
+ `$1`…`$n` to positional arguments, and `` !`shell` `` to captured shell output
243
+ at invocation time:
244
+
245
+ ```markdown
246
+ ---
247
+ description: Generate a commit message for staged changes
248
+ model: deveco/kimi-k2.5
249
+ subagent: true
250
+ ---
251
+
252
+ Generate a commit message for the following changes:
253
+
254
+ !`git diff --cached`
255
+ ```
256
+
257
+ Inline form: the `commands` record in `deveco.json` (`template` is required).
258
+
259
+ ## Skills
260
+
261
+ A skill is a directory with a `SKILL.md` (or a loose `*.md` file) under
262
+ `.deveco/skill(s)/` or `~/.config/deveco/skill(s)/`:
263
+
264
+ ```
265
+ .deveco/skills/my-skill/SKILL.md
266
+ ```
267
+
268
+ Frontmatter: `name` (display name; the skill **id** comes from the directory
269
+ or file name), `description` (the model-facing trigger — front-load the
270
+ keywords users will say, write "Use when…", gate with "Use ONLY when…"),
271
+ `metadata` (e.g. `opencode/autoinvoke`), `disable-model-invocation`. The body
272
+ is injected into the conversation when the skill loads; sibling files
273
+ (`references/`, `scripts/`) stay on disk and are read or executed relative to
274
+ the skill directory the loader reports.
275
+
276
+ Extra sources: the `skills` config array (directory paths scanned recursively,
277
+ or http(s) URLs serving an `index.json` of `{skills:[{name,version?,files[]}]}`,
278
+ cached under `~/.cache/deveco/skills/`). Compatibility roots `~/.claude/skills`
279
+ and `~/.agents/skills` are always scanned too.
280
+
281
+ Built-in skills ship with the product and are never toggleable:
282
+ `customize-deveco` (this guide), `deveco-cli`, `hmos-arkui-develop-skill`,
283
+ `hmos-runtime-fix-skill`. All other skills can be disabled globally or
284
+ per-project; the choices persist in `~/.config/deveco/skill-preferences.json`.
285
+
286
+ ## Plugins (v2 API)
287
+
288
+ A plugin module has a **default export** with an id and one of:
289
+
290
+ ```ts
291
+ import { define } from "@opencode/plugin/effect/plugin"
292
+
293
+ export default define({
294
+ id: "my-plugin",
295
+ effect: (ctx) => /* Effect: transforms, tools, rpc, events */,
296
+ })
297
+ ```
298
+
299
+ or a promise-style `setup`:
300
+
301
+ ```ts
302
+ export default {
303
+ id: "my-plugin",
304
+ setup: async (ctx) => {
305
+ /* register hooks/transforms */
306
+ },
307
+ }
308
+ ```
309
+
310
+ The v1 function-returning-hooks shape (`(input) => Promise<Hooks>`) is **not**
311
+ the v2 contract — a module without `{id, effect|setup}` fails to load. Import
312
+ paths keep the upstream `@opencode/plugin` package names.
313
+
314
+ Sources, in activation order: built-ins → auto-discovered `.ts`/`.js` files or
315
+ directories in `~/.config/deveco/{plugin,plugins}/` and every
316
+ `.deveco/{plugin,plugins}/` → `plugins` config entries (npm/git specs install
317
+ into `~/.cache/deveco/npm/`; `"-<target>"` entries remove). Directory plugins
318
+ resolve entrypoints `server` (or `index`), `tui`, `rpc`. Local plugin files are
319
+ watched and hot-reloaded. Manage installed packages with `deveco plugin
320
+ list|add|check|update|remove`. For the full hook/transform/tool/RPC surface,
321
+ see the upstream plugin guides in the translation section below.
322
+
323
+ ## MCP servers
324
+
325
+ Configure under `mcp.servers` (see field guide) or via CLI — the CLI preserves
326
+ unrelated config and is the safer edit:
327
+
328
+ ```sh
329
+ deveco mcp add <name> --global --url <remote-url>
330
+ deveco mcp list
331
+ ```
332
+
333
+ Remote servers default to OAuth; when `deveco mcp list` reports a server needs
334
+ authentication, sign in through the TUI's `/mcps` dialog rather than `deveco
335
+ mcp auth` in a shell (the interactive authorization link can be swallowed by
336
+ background output). Credentials live outside the config; prefer
337
+ `{env:VAR}`/`{file:path}` substitution over inline secrets in `headers`.
338
+
339
+ ## Permissions
340
+
341
+ Native v2 form is the flat `permissions` rule array
342
+ (`{action, resource, effect: "allow"|"ask"|"deny"}`); both fields support
343
+ wildcards and the **last matching rule wins** — broad rules first, narrow
344
+ rules last. Per-agent `permissions` override the global ruleset for that
345
+ agent. Common actions: `edit`, `read`, `shell`, `subagent`, `webfetch`,
346
+ `websearch`, `question`, `skill`, `external_directory`, plus one per registered
347
+ tool (e.g. `verify_ui`, `spec_write`). The v1 `permission` object and
348
+ `tools: {name: bool}` map still load through migration.
349
+
350
+ ## Themes and keybinds (cli.json)
351
+
352
+ Custom themes are `<name>.json` files in `~/.config/deveco/themes/` or any
353
+ ancestor `.deveco/themes/` directory, shaped `{ $schema?, base, light?, dark? }`
354
+ (complete token trees; at least one of light/dark). Selection lives in
355
+ `cli.json`: `"theme": { "name": "...", "mode": "system"|"dark"|"light" }`; the
356
+ product default theme is `deveco`. The TUI picks up theme file changes on
357
+ `SIGUSR2`.
358
+
359
+ Keybinds live in `cli.json` under `keybinds` (leader default `ctrl+x`,
360
+ timeout under `leader.timeout`; disable a binding with `"none"` or `false`;
361
+ unknown keys are rejected). Do not guess command ids or key syntax — read the
362
+ current defaults via the upstream keybind reference (translation section) or
363
+ `Ctrl+P` → **Open settings** in the TUI. `OPENCODE_CLI_CONFIG_CONTENT` merges
364
+ inline JSON over `cli.json` for one-off runs; the TUI hot-reloads the file.
365
+
366
+ ## CLI and service
367
+
368
+ Binary: `deveco`. Subcommands: *(no args)* TUI · `run` one-shot prompt ·
369
+ `mini` minimal interface · `serve` explicit server · `api` request the running
370
+ server · `acp` Agent Client Protocol server · `auth` credentials · `mcp` ·
371
+ `plugin` · `session list|delete|export|import` · `service
372
+ start|restart|status|stop|get|set|unset` · `reload` config · `models` ·
373
+ `stats` · `pair` browser/app links · `debug agents|config|paths` · `upgrade` ·
374
+ `uninstall`.
375
+
376
+ The TUI connects to a shared background service that owns sessions, config,
377
+ plugins, and tool execution. If it misbehaves:
378
+
379
+ ```sh
380
+ deveco service status
381
+ deveco service restart
382
+ deveco api get /api/info
383
+ ```
384
+
385
+ ## Logs, debugging, escape hatches
386
+
387
+ - Log file: `~/.local/share/deveco/log/deveco.log`. Filter `role=cli` for
388
+ client startup and `role=server` for sessions, providers, plugins,
389
+ permissions, tools.
390
+ - Verbose one-off run: `DEVECO_LOG_LEVEL=DEBUG DEVECO_PRINT_LOGS=1 deveco`.
391
+ - Env vars accept both prefixes — `DEVECO_*` wins, `OPENCODE_*` is the
392
+ fallback (a few internal-only vars are `OPENCODE_*` exclusively, e.g.
393
+ `OPENCODE_CLI_CONFIG_CONTENT`, `OPENCODE_DB`, `OPENCODE_TEST_HOME`).
394
+
395
+ | Var | Effect |
396
+ | --- | --- |
397
+ | `DEVECO_CONFIG_DIR` | use a different global config dir |
398
+ | `DEVECO_CONFIG` | load one additional explicit config file |
399
+ | `DEVECO_CONFIG_CONTENT` | inline JSONC merged at highest precedence |
400
+ | `DEVECO_CONFIG_PROJECT_DISABLE` | skip project config walk-up (also skips project `AGENTS.md`) |
401
+ | `OPENCODE_FILEWATCHER_DISABLE` | disable file watching |
402
+ | `DEVECO_MODELS_URL` / `DEVECO_MODELS_PATH` / `DEVECO_DISABLE_MODELS_FETCH` | model catalog source |
403
+ | `DEVECO_HOME` | DevEco Studio installation (HarmonyOS tooling) |
404
+ | `XDG_CONFIG_HOME` / `XDG_DATA_HOME` / `XDG_STATE_HOME` / `XDG_CACHE_HOME` | relocate the global dirs (read at process start) |
405
+
406
+ Broken-project-config playbook: start once with
407
+ `DEVECO_CONFIG_PROJECT_DISABLE=1` from the project directory, fix the
408
+ offending `deveco.json(c)` from inside the running session, then restart
409
+ without the flag.
410
+
411
+ ## DevEco product notes
412
+
413
+ - The built-in `deveco` provider serves DevEco-account models (login through
414
+ the TUI); upstream opencode free-tier models are disabled in this product.
415
+ - Feedback goes through the `/complain` page, not upstream GitHub issues.
416
+ Privacy, data-collection, and language settings live behind `/privacy`,
417
+ `/collect`, `/language`.
418
+ - HarmonyOS work rides the `deveco-cli`, `hmos-arkui-develop-skill`, and
419
+ `hmos-runtime-fix-skill` built-ins plus the `devecocli` shim on the session
420
+ shell PATH.
421
+
422
+ ## Upstream V2 documentation (network permitting)
423
+
424
+ Answer for **V2**. Upstream docs are OpenCode-branded; translate before
425
+ applying, and never infer v2 config shapes from `https://opencode.ai/config.json`
426
+ (it describes V1). Machine-readable index: `https://opencode.ai/v2/llms.txt`.
427
+
428
+ | Topic | URL |
429
+ | --- | --- |
430
+ | Configuration | `/v2/docs/config` |
431
+ | CLI + settings + keybinds | `/v2/docs/cli`, `/v2/docs/cli/config`, `/v2/docs/cli/keybinds` |
432
+ | MCP servers | `/v2/docs/mcp-servers` |
433
+ | V1→V2 migration | `/v2/docs/migrate-v1` |
434
+ | Plugins (+ CLI plugins, RPC) | `/v2/docs/build/plugins`, `…/plugins/cli`, `…/plugins/rpc` |
435
+ | Troubleshooting / service | `/v2/docs/troubleshooting` |
436
+ | HTTP API | `/v2/docs/api` (live spec at `/openapi.json` on the server) |
437
+ | TypeScript client / SDK | `/v2/docs/build/client`, `/v2/docs/build/sdk` |
438
+
439
+ (all under `https://opencode.ai`)
440
+
441
+ Translation table:
442
+
443
+ | Upstream | DevEco Code |
444
+ | --- | --- |
445
+ | `opencode` (binary) | `deveco` |
446
+ | OpenCode | DevEco Code |
447
+ | `opencode.json(c)` | `deveco.json(c)` |
448
+ | `.opencode/` | `.deveco/` |
449
+ | `~/.config/opencode`, `~/.local/share/opencode` | `~/.config/deveco`, `~/.local/share/deveco` |
450
+ | `OPENCODE_*` env | `DEVECO_*` preferred (both accepted) |
451
+ | `@opencode/*` npm imports in plugin code | unchanged (`@opencode/plugin`, …) |
452
+
453
+ Upstream features that do not apply here: GitHub issue reporting, the
454
+ opencode account/zen surface, and `share` autosharing — omit them from
455
+ recommendations.
456
+
457
+ ## When proposing edits
458
+
459
+ - Ground every field in this guide or the codebase; when unsure of an exact
460
+ shape, say so instead of guessing, and fetch the matching upstream page if
461
+ the network allows.
462
+ - Preserve `$schema` and unrelated fields when editing an existing file.
463
+ - Prefer file forms (`.deveco/agent(s)/`, `command(s)/`, `skills/`,
464
+ `plugins/`) over inlining everything into `deveco.json`.
465
+ - Themes and keybinds belong in `cli.json`, never in `deveco.json(c)`.
466
+ - Config hot-reloads — do not tell users to restart after ordinary config
467
+ edits; reserve `deveco service restart` for service settings and env changes.
468
+ - If a broken config blocks startup, walk the user through the
469
+ `DEVECO_CONFIG_PROJECT_DISABLE` playbook above.
@@ -0,0 +1 @@
1
+ deveco-cli