@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.
- package/CHANGELOG.md +13 -0
- package/package.json +6 -5
- package/resources/deveco/skills/customize-deveco/.deveco-builtin +1 -0
- package/resources/deveco/skills/customize-deveco/SKILL.md +469 -0
- package/resources/deveco/skills/deveco-cli/.deveco-builtin +1 -0
- package/resources/deveco/skills/deveco-cli/SKILL.md +240 -0
- package/resources/deveco/skills/hmos-arkui-develop-skill/.deveco-builtin +1 -0
- package/resources/deveco/skills/hmos-arkui-develop-skill/SKILL.md +83 -0
- package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-apis/01-layout.md +629 -0
- package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-apis/02-basic-components.md +645 -0
- package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-apis/03-data-display.md +81 -0
- package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-apis/04-selectors.md +76 -0
- package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-apis/05-media.md +60 -0
- package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-apis/06-advanced.md +32 -0
- package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-apis/07-security.md +30 -0
- package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-apis/08-state-decorators.md +79 -0
- package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-apis/09-animation.md +111 -0
- package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-apis/10-gesture.md +59 -0
- package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-apis/11-dialog-menu.md +92 -0
- package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-apis/12-navigation.md +81 -0
- package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-apis/13-rendering.md +22 -0
- package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-apis/14-extension.md +22 -0
- package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-apis/15-theme-style.md +10 -0
- package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-apis/16-enums.md +87 -0
- package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-apis/17-resources.md +1379 -0
- package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-apis/18-error-code.md +24 -0
- package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-apis/_index.md +75 -0
- package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-rules/00-arkts-syntax.md +229 -0
- package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-rules/01-import.md +116 -0
- package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-rules/02-uicontext.md +56 -0
- package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-rules/03-component.md +105 -0
- package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-rules/04-build.md +41 -0
- package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-rules/05-state.md +300 -0
- package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-rules/06-rendering.md +67 -0
- package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-rules/07-attribute-params.md +219 -0
- package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-rules/08-navigation.md +102 -0
- package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-rules/09-dialog.md +72 -0
- package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-rules/10-style.md +90 -0
- package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-rules/11-extension.md +54 -0
- package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-rules/12-layout.md +69 -0
- package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-rules/13-performance.md +27 -0
- package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-rules/14-deprecated.md +28 -0
- package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-rules/_index.md +79 -0
- package/resources/deveco/skills/hmos-runtime-fix-skill/.deveco-builtin +1 -0
- package/resources/deveco/skills/hmos-runtime-fix-skill/SKILL.md +187 -0
- package/resources/deveco/skills/hmos-runtime-fix-skill/SKILL_CN.md +160 -0
- package/resources/deveco/skills/hmos-runtime-fix-skill/evals/evals.json +17 -0
- package/resources/deveco/skills/hmos-runtime-fix-skill/reference/businesserror_patterns.md +17 -0
- package/resources/deveco/skills/hmos-runtime-fix-skill/reference/error_patterns.md +31 -0
- package/resources/deveco/skills/hmos-runtime-fix-skill/reference/fault-mode-library.md +57 -0
- package/resources/deveco/skills/hmos-runtime-fix-skill/reference/outofmemoryerror_patterns.md +19 -0
- package/resources/deveco/skills/hmos-runtime-fix-skill/reference/rangeerror_patterns.md +15 -0
- package/resources/deveco/skills/hmos-runtime-fix-skill/reference/referenceerror_patterns.md +23 -0
- package/resources/deveco/skills/hmos-runtime-fix-skill/reference/syntaxerror_patterns.md +14 -0
- package/resources/deveco/skills/hmos-runtime-fix-skill/reference/typeerror_patterns.md +19 -0
- package/resources/deveco/skills/hmos-runtime-fix-skill/reference/urierror_patterns.md +17 -0
- package/resources/deveco/skills/hmos-runtime-fix-skill/scripts/collect-hilog.mjs +120 -0
- package/resources/deveco/skills/hmos-runtime-fix-skill/scripts/jscrash-report.mjs +138 -0
- package/resources/deveco/skills/hmos-runtime-fix-skill/scripts/parse-jscrash-log.mjs +126 -0
- package/resources/deveco/skills/hmos-runtime-fix-skill/scripts/shared/deveco-cli.mjs +79 -0
- package/resources/deveco/skills/hmos-runtime-fix-skill/scripts/shared/jscrash-parse.mjs +389 -0
- 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.
|
|
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.
|
|
30
|
-
"@deveco-test/deveco-code-darwin-x64": "1.0.
|
|
31
|
-
"@deveco-test/deveco-code-darwin-arm64": "1.0.
|
|
32
|
-
"@deveco-test/deveco-code-openharmony-arm64": "1.0.
|
|
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
|