Skip to content

armgit / Orkas

Public Imported from GitHub
0

Orkas is an open-source (MIT), local-first AI team for your desktop: a Commander turns your goal into to-dos and coordinates 16 built-in specialist agents plus Claude Code, Codex, OpenCode, OpenClaw and Hermes, with projects, scheduled automations and connectors. Free app for macOS & Windows; built-in models or your own keys.

Tighten prose-language directive and detail agent name charset error

claw2d20358e26960
diff --git a/src/main/features/agents.ts b/src/main/features/agents.ts
index cbcbe3b5..434a907e 100644
--- a/src/main/features/agents.ts
+++ b/src/main/features/agents.ts
@@ -310,7 +310,21 @@ function assertAgentNameCharsetValid(name: string): void {
throw err;
}
if (!NAME_TOKEN_RE.test(trimmed)) {
- const err: any = new Error(`agent name contains unsupported characters (only letters, digits, hyphen, underscore, CJK, and single internal spaces are allowed)`);
+ // Surface the offending literal + the specific bad chars so a streamed
+ // error feeds the LLM enough signal to self-correct on the next turn,
+ // instead of repeating the same forbidden character.
+ const SINGLE_TOKEN_CHAR_RE = /[A-Za-z0-9_一-鿿-]/;
+ const bad: string[] = [];
+ const seen = new Set<string>();
+ for (const ch of trimmed) {
+ if (ch === ' ') continue;
+ if (SINGLE_TOKEN_CHAR_RE.test(ch)) continue;
+ if (!seen.has(ch)) { seen.add(ch); bad.push(ch); }
+ }
+ const detail = bad.length
+ ? `forbidden character${bad.length > 1 ? 's' : ''}: ${bad.map(c => `\`${c}\``).join(' ')}`
+ : 'multiple consecutive spaces are not allowed (only single internal spaces between tokens)';
+ const err: any = new Error(`agent name "${trimmed}" contains unsupported characters — ${detail}. Allowed: ASCII letters / digits / \`_\` / \`-\` / CJK U+4E00–U+9FFF / single internal spaces. Forbidden include \`/\` \`\\\` \`.\` \`,\` \`(\` \`)\` \`:\` \`!\` \`?\`, full-width punctuation, kana, hangul, extended-CJK, emoji.`);
err.code = 'E_AGENT_NAME_INVALID';
throw err;
}
diff --git a/src/main/i18n.ts b/src/main/i18n.ts
index a951e045..1e87b4a5 100644
--- a/src/main/i18n.ts
+++ b/src/main/i18n.ts
@@ -127,7 +127,11 @@ export function buildLanguageDirective(lang: Lang = _current): string {
return [
'## User language',
'',
- `The user's UI language is set to **${name}**. All natural-language replies you write to the user (final text, form lead-ins, announcements, status notes) MUST be in ${name}. Tool calls, code, JSON payloads, structured tags (e.g. \`<agent>\`, \`<agent-input-form>\`), filenames and paths stay in their native form regardless of language.`,
+ `The user's UI language is set to **${name}**. Every piece of human-readable prose you produce — final replies, form lead-ins, announcements, status notes, AND **the natural-language content inside any structured tag or JSON field** (e.g. \`<workflow>\` step titles and step body descriptions, \`<inputs>\` / \`<agent-input-form>\` field \`label\` values, \`plan_set\` step \`title\` and \`input\` strings, \`<agent>\` container prose) — MUST be in ${name}.`,
+ '',
+ `What stays in its native form regardless of language: XML tag names themselves (\`<agent>\` / \`<workflow>\` / \`<inputs>\` etc.; do not translate the tag), tool names and skill_ids written in backticks (\`read_file\` / \`kb_search\` / \`web_fetch\` / etc.), JSON object keys (\`"id"\` / \`"type"\` / \`"options"\` / \`"value"\`), file paths, code snippets, and \`value\` strings inside \`select\` / \`multiselect\` options (the value is an internal id; the matching \`label\` is what gets translated).`,
+ '',
+ `Bilingual description fields are pinned by suffix and ignore the UI language: \`<description_zh>\` / \`description_zh\` always carries Chinese; \`<description_en>\` / \`description_en\` always carries English. Examples in this system prompt may be written in English to illustrate shape — when you produce the actual content, write it in ${name}, not by copying the example's language.`,
].join('\n');
}
diff --git a/src/main/prompts/chat_agent_in_group.md b/src/main/prompts/chat_agent_in_group.md
index 16416f25..204fcee5 100644
--- a/src/main/prompts/chat_agent_in_group.md
+++ b/src/main/prompts/chat_agent_in_group.md
@@ -56,14 +56,16 @@ Only **fully-no-information-needed** turns (pure result reports / pure conclusio
> Self-check rule of thumb: the moment you start to type "1. ... 2. ... 3. ..." or "could you tell me ..." or "please confirm ...", **stop immediately** and turn those points into a `fields` array in a form.
-**Form format** (XML tag wrapping JSON, output at the end of the final text, **send only once**, with one or two sentences before the block telling the user what you need to confirm):
+**Form format** (XML tag wrapping JSON; output at the end of the final text, **send only once**, with one or two sentences before the block telling the user what you need to confirm):
```
<agent-input-form>
{
"fields": [
- {"id": "topic", "label": "Topic", "type": "text", "required": true},
- {"id": "depth", "label": "Analysis depth", "type": "select", "options": [{"value":"quick","label":"Quick"},{"value":"deep","label":"Deep"}], "default": "quick"}
+ {"id": "<snake_case_id>", "label": "<label in user UI language>", "type": "text", "required": true},
+ {"id": "<id>", "label": "<label in UI language>", "type": "select",
+ "options": [{"value":"<internal_id_a>","label":"<display in UI language>"},{"value":"<internal_id_b>","label":"<display in UI language>"}],
+ "default": "<internal_id_a>"}
]
}
</agent-input-form>
diff --git a/src/main/prompts/chat_agent_setup.md b/src/main/prompts/chat_agent_setup.md
index 1a73b95b..db42ec57 100644
--- a/src/main/prompts/chat_agent_setup.md
+++ b/src/main/prompts/chat_agent_setup.md
@@ -9,32 +9,15 @@ You are working with the user to refine a custom agent — polish its "name / de
2. **Refine the workflow**: workflow is a set of **steps executed in order**. Format per step:
```
- ### N. <imperative-mood step title, 5–10 chars>
- - `tool_name(key params)` — one-line purpose
+ ### N. <verb-led step title, 5–10 chars>
+ - `tool_name(key params)` — one-line purpose & inline result
- next action ... (in physical order)
- branches use nested bullets (`if X → call A` / `else → call B`)
-
- **Output**: <file path / data structure / specific shape delivered to the user, etc. — concrete consumables. Omit this line for steps with no concrete output.>
- ```
-
- **Example** (typical pipeline):
-
```
- ### 1. Take form params
- - Read the user-submitted inputs form directly (keywords / platforms / time range); no tool call needed.
-
- **Output**: a query object (keywords + platforms + time range)
- ### 2. Fetch and analyze
- - `social-fetch` skill — fetch posts on each platform per the query
- - `kb_search(keyword)` — pull past analyses on the same topic for reference
+ The previous step's result / inbound message / accumulated session context are the default carry-over and need not be restated. Exception handling / retry / skip is decided by the runtime agent, not written into the workflow.
- **Output**: a markdown sentiment/trend report, delivered to the user
- ```
-
- **Don't write an "Input" field** — the previous step's output / inbound message / accumulated session context are the default carry-over; writing them out is pure noise. Genuinely non-default inputs (reading a specific file / querying a KB) just appear as the first action (e.g. `read_file(...)`). The **"Output"** line is included only when the step produces a consumable (a file written / a form triggered / a clear deliverable to the user); for steps that are pure internal reasoning / plain conversational turns, omit it. Exception handling / retry / skip is decided by the runtime agent, **not written into the workflow**.
-
- **Hard constraint — every action must explicitly write the tool name / skill_id** (e.g. `read_file` / `kb_search` / `social-fetch` skill); do NOT write abstract verbs like "read the file" / "do a search". Why: ① workflow is injected into the runtime agent's system prompt; missing tool names force secondary inference, which often picks the wrong tool or misses one; ② the `<skills>` closure is extracted from skill_ids that appear in workflow — without skill_id, the closure can't be derived.
+ **Hard constraint — every action must explicitly write the tool name / skill_id** in backticks (e.g. `read_file` / `kb_search` / `social-fetch` skill); do NOT write abstract verbs like "read the file" / "do a search". Why: ① workflow is injected into the runtime agent's system prompt; missing tool names force secondary inference, which often picks the wrong tool or misses one; ② the `<skills>` closure is extracted from skill_ids that appear in workflow — without skill_id, the closure can't be derived.
3. **Implementation: built-in tools vs skill** (pick in this order):
- **First check built-in tools** (auto-registered via the tool-use protocol) — read/write file, bash, KB search, PDF render, image generation, web search/fetch, etc. — single-step actions that run directly. **No skill wrapper needed**; in workflow, write the tool name verbatim ("use `read_file` to read the PDF" / "use `markdown_to_pdf` to render the report" / "use `kb_search` to query the KB"); don't force-wrap a single-step action as a skill.
- **Then check the "Available skills (skills)" section** — skills are most useful for: multi-step logic encapsulation, third-party paid APIs (with credential management), recurrent compound flows. If one fits, use it; don't reinvent the wheel.
@@ -60,21 +43,17 @@ The conversation prose to the user (content **outside** the `<agent>` container)
- Field names / XML tags: `interactive` / `inputs` / `skills` / `workflow` / `description` / `description_zh` / `description_en` / `name` / `<agent>` / `<inputs>` / `<workflow>` / any `<xxx>` tag.
- Data-structure terms: `schema` / `frontmatter` / `JSON` / `closure` / "closure" / `select` / `multiselect` / `options` / `default` / `required` / "field" / "sub-tag" / "container" / "config" / "write-back" / id.
-**Translation table** (use user-perspective wording for these concepts):
-- `interactive=true` → "It will chat with you back and forth."
-- `interactive=false` → "It runs autonomously and won't need you to reply midway."
-- Editing `inputs` → "Before running, it asks you these things: A, B, C."
-- Editing `skills` → "It uses these capabilities: X and Y."
-- Editing `workflow` → "I organized the steps it follows into ..."
-- Editing `description_zh` / `description_en` / `name` → "I updated its description / name to ..." (don't expose specific field names; don't say "the Chinese description was changed / the English description was changed" — the user does not need to know it's a bilingual field).
-
-**Wrong example**:
-
-> Updated: `interactive` is `false`, `inputs` got a `time_range` select with default `1m`, `skills` closure includes `social-fetch` + `agent-browser`.
-
-**Right example**:
+**Map field changes to user-perspective concepts** (write the actual sentence in the user's UI language; the descriptions below are abstract patterns, not literal phrasings to copy):
+- `interactive=true` → describe as "the agent will chat back and forth with the user".
+- `interactive=false` → describe as "the agent runs autonomously, no mid-task reply needed".
+- editing `inputs` → describe as "what the form asks the user before running".
+- editing `skills` → describe as "what capabilities the agent uses".
+- editing `workflow` → describe as "what steps the agent follows / how it does the task".
+- editing `description_zh` / `description_en` / `name` → describe as "I updated its <description> / <name> to ..." without exposing the bilingual nature or specific field names.
-> It runs the whole scraping flow autonomously and won't need you to reply midway; before running, it asks you the "time range", defaulting to one month; it uses the built-in "social media scraping" capability.
+**Style contrast**:
+- ✗ exposing internals: writes field names (`interactive` / `inputs` / etc.), data-structure terms, ids, or "closure"-flavoured language.
+- ✓ user-perspective: describes the change in plain prose using what the user cares about (when it runs, what it asks beforehand, what capabilities it uses, what it produces).
---
@@ -102,16 +81,13 @@ skill_id_2
</skills>
<inputs>
[
- {"id":"keywords","label":"Keywords","type":"text","default":"","placeholder":"e.g. Claude Code reviews","required":true},
- {"id":"platforms","label":"Platforms","type":"multiselect",
- "options":[{"value":"xhs","label":"Xiaohongshu"},{"value":"reddit","label":"Reddit"},{"value":"x","label":"X"},{"value":"bilibili","label":"Bilibili"},{"value":"youtube","label":"YouTube"}],
- "default":["xhs","reddit","x","bilibili","youtube"]},
- {"id":"time_range","label":"Time range","type":"select",
- "options":[{"value":"1w","label":"Last week"},{"value":"1m","label":"Last month"},{"value":"3m","label":"Last 3 months"}],
- "default":"1m"},
- {"id":"depth","label":"Analysis depth","type":"select",
- "options":[{"value":"normal","label":"Normal"},{"value":"deep","label":"Deep"}],
- "default":"normal"}
+ {"id":"<snake_case_id>","label":"<label in user UI language>","type":"text","default":"","placeholder":"<placeholder in user UI language>","required":true},
+ {"id":"<id>","label":"<label in user UI language>","type":"multiselect",
+ "options":[{"value":"<internal_id_a>","label":"<display in UI language>"},{"value":"<internal_id_b>","label":"<display in UI language>"}],
+ "default":["<internal_id_a>"]},
+ {"id":"<id>","label":"<label in UI language>","type":"select",
+ "options":[{"value":"<internal_id>","label":"<display in UI language>"}],
+ "default":"<internal_id>"}
]
</inputs>
<interactive>false</interactive>
@@ -121,6 +97,7 @@ skill_id_2
Rules:
- **At most one `<agent>...</agent>` container per turn**. Put the fields to be changed inside as sub-tags; omit the sub-tags for fields that aren't changing.
- Each sub-tag **overwrites** the field's prior content — if you want to keep old content, write the old content into the sub-tag.
+- **`<name>` charset is strictly limited** to: ASCII letters / digits / `_` / `-` / CJK Unified Ideographs U+4E00–U+9FFF / single internal spaces between tokens. **Forbidden**: `/` `\` `.` `,` `(` `)` `:` `;` `!` `?`, full-width punctuation (`·` `(` `)` `:` `。` `,` etc.), Japanese kana (ひらがな / カタカナ), Korean Hangul, CJK Extension A/B+ (less common ideographs), and emoji. **Why**: the bus's `@`-mention router uses regex token class `[A-Za-z0-9_一-鿿-]`; a name containing any other character makes `@<name>` truncate at the first illegal char and routes the dispatch to the wrong agent (or to nothing). Pick neutral tokens — `Code Reviewer` / `代码审查官` / `agent-skill-评估` are fine; `Agent/Skill 评估` / `Helper.v2` / `助手·Pro` / `アシスタント` are rejected by the validator and the conversation will fail.
- `<skills>` content = the skill_ids actually used by the current (latest) workflow, one per line.
- **An empty `<skills></skills>` is common, legal, and recommended** — many agents need no skills at all (pure file / KB / web / PDF / image-gen / bash tasks complete with built-in tools). **Don't stuff in skills just because the system prompt lists many**; skills not actually used by the workflow must NOT be written.
- skill_ids must come from the system prompt's "Available skills (skills)" section; do not invent or misspell. **Built-in tool names are NOT skill_ids** and must never appear in `<skills>`.
@@ -141,15 +118,15 @@ This field decides "when the user runs this agent, which parameters does the mai
**Each input must have**:
- `id`: snake_case, unique within the agent, regex `^[a-z_][a-z0-9_]{0,31}$`.
-- `label`: a short user-facing phrase ("Keywords" / "Platforms" / "Time range") — no pinyin, no English ids in the label.
+- `label`: a short user-facing phrase **in the user's UI language** — no pinyin, no internal ids in the label.
- `type`: one of `text` / `textarea` / `select` / `multiselect` / `number` / `boolean` / `file`.
- `default`: **must be provided**. For options, pick the most common; for free text, `""`; for multiselect, `[]` (default deselected) or a reasonable all/common subset; boolean follows the "default on/off" of the workflow; `file` is always `""` (single) or `[]` (multi) — you can't pick the file for the user.
-- `select`/`multiselect` must include `options: [{value, label}, ...]`; `value` is the string passed to the workflow (English ids are easier), `label` is the user-facing display; `default` must be a value present in options (or a subset for multiselect).
+- `select`/`multiselect` must include `options: [{value, label}, ...]`; `value` is the internal id passed to the workflow (lowercase ASCII snake_case), `label` is the user-facing display in the user's UI language; `default` must be a value present in options (or a subset for multiselect).
**Optional fields**:
-- `description`: helper text under the label (e.g. "if blank, will infer from common sense").
+- `description`: helper text under the label, in the user's UI language.
- `required`: when true, the form validates non-empty (also supported for `file`, requiring at least one file).
-- `placeholder`: placeholder for text/textarea/number.
+- `placeholder`: placeholder for text / textarea / number, in the user's UI language.
- `min` / `max`: numeric bounds.
- `file`-only: `multiple: true` (allow multi-select; submitted value is `string[]`), `accept: ".pdf,.docx,image/*"` (recommended; constrains the picker's visible types but does not enforce server-side).
- No `show_if` or other conditional logic — the schema must be visible at a glance.
@@ -162,7 +139,7 @@ This field decides "when the user runs this agent, which parameters does the mai
**When to NOT emit the block**: this round, the user asks something unrelated to inputs (changing description, small talk, etc.). Don't rewrite the schema out of nowhere.
-**Coordination with workflow**: the parts of workflow describing "default parameters / option values" should be isomorphic with the inputs schema (workflow says "default 1 month; choose between 1 week / 1 month / 3 months" → select options must match). Sync strategy is in the "Field sync policy" above. Full format is shown in the `<inputs>` segment of the `<agent>` container example above.
+**Coordination with workflow**: the parts of workflow describing "default parameters / option values" must stay isomorphic with the inputs schema — when the workflow names a default and an option set, the corresponding `select` `options` and `default` must match. Sync strategy is in the "Field sync policy" above. Full format is shown in the `<inputs>` segment of the `<agent>` container example above.
---
diff --git a/src/main/prompts/chat_agent_setup_cli.md b/src/main/prompts/chat_agent_setup_cli.md
index dc441568..3e257934 100644
--- a/src/main/prompts/chat_agent_setup_cli.md
+++ b/src/main/prompts/chat_agent_setup_cli.md
@@ -75,9 +75,9 @@ Format:
<description_en>The new English description (same three-part formula)</description_en>
<inputs>
[
- {"id":"focus","label":"Review focus","type":"select",
- "options":[{"value":"logic","label":"Logic bugs"},{"value":"security","label":"Security"},{"value":"both","label":"Both"}],
- "default":"both"}
+ {"id":"<snake_case_id>","label":"<label in user UI language>","type":"select",
+ "options":[{"value":"<internal_id_a>","label":"<display in UI language>"},{"value":"<internal_id_b>","label":"<display in UI language>"}],
+ "default":"<internal_id_a>"}
]
</inputs>
<interactive>false</interactive>
@@ -86,6 +86,7 @@ Format:
Rules:
- **At most one `<agent>...</agent>` container per turn**. Put the fields to be changed inside as sub-tags; omit the sub-tags for fields that aren't changing.
+- **`<name>` charset is strictly limited**: ASCII letters / digits / `_` / `-` / CJK U+4E00–U+9FFF / single internal spaces. Forbidden: `/` `\` `.` `,` `(` `)` `:` `!` `?`, full-width punctuation, kana, hangul, extended-CJK, emoji. **Why**: the `@`-mention router truncates at the first illegal char, mis-routing the dispatch. The validator rejects offending names with `E_AGENT_NAME_INVALID` and the edit fails.
- Each sub-tag **overwrites** the field's prior content — if you want to keep old content, write the old content into the sub-tag.
- The `<agent>` container is auto-hidden from the user-visible message.
- **Do NOT** insert anything other than the listed sub-tags inside the `<agent>` container; user-facing text goes into the prose outside the container.
@@ -101,7 +102,7 @@ This field decides "when the user runs this agent, which parameters does the mai
**Each input must have**:
- `id`: snake_case, unique within the agent, regex `^[a-z_][a-z0-9_]{0,31}$`.
-- `label`: a short user-facing phrase ("Review focus" / "Target stack") — no pinyin, no English ids in the label.
+- `label`: a short user-facing phrase **in the user's UI language** — no pinyin, no internal ids in the label.
- `type`: one of `text` / `textarea` / `select` / `multiselect` / `number` / `boolean` / `file`.
- `default`: **must be provided**. For options, pick the most common; for free text, `""`; for multiselect, `[]` or a reasonable subset; boolean follows the "default on/off" of the agent; `file` is always `""` (single) or `[]` (multi).
- `select`/`multiselect` must include `options: [{value, label}, ...]`.
diff --git a/src/main/prompts/chat_commander.md b/src/main/prompts/chat_commander.md
index 2bd9f6da..b4df5eac 100644
--- a/src/main/prompts/chat_commander.md
+++ b/src/main/prompts/chat_commander.md
@@ -139,50 +139,46 @@ Variables that don't exist are left literal (handy for debugging).
### Three typical shapes
-**Parallel**:
+The skeletons below show JSON structure only. Field rules: `title` and `input` are user-facing and must be written in the user's UI language; `assignee` is an exact agent name from the Agents list (or `commander` / `user`); template tokens `{{user_initial_message}}` / `{{step_N.output_summary}}` / `{{step_N.output_files}}` stay literal.
+
+**Parallel** (steps in the same `parallel_group` with `wait_for: []` run simultaneously; a synthesis step waits on all of them):
```
plan_set({
- initial_message: "Should I quit my job?",
+ initial_message: "<user's original message>",
steps: [
- { title: "Optimistic analysis", assignee: "Optimist", input: "Analyze from an optimistic angle: {{user_initial_message}}", wait_for: [], parallel_group: "analyze" },
- { title: "Pessimistic analysis", assignee: "Pessimist", input: "Analyze from a pessimistic angle: {{user_initial_message}}", wait_for: [], parallel_group: "analyze" },
- { title: "Holistic evaluation", assignee: "Holistic Evaluator", input: "Holistic evaluation: {{user_initial_message}}", wait_for: [], parallel_group: "analyze" },
- { title: "Synthesize", assignee: "commander", input: "Synthesize the three views for the user: A={{step_1.output_summary}} / B={{step_2.output_summary}} / C={{step_3.output_summary}}", wait_for: [1,2,3] }
+ { title: "<step 1 title>", assignee: "<agent A>", input: "<task using {{user_initial_message}}>", wait_for: [], parallel_group: "<group>" },
+ { title: "<step 2 title>", assignee: "<agent B>", input: "<task using {{user_initial_message}}>", wait_for: [], parallel_group: "<group>" },
+ { title: "<step 3 title>", assignee: "<agent C>", input: "<task using {{user_initial_message}}>", wait_for: [], parallel_group: "<group>" },
+ { title: "<synthesis title>", assignee: "commander", input: "<synth using {{step_1.output_summary}} / {{step_2.output_summary}} / {{step_3.output_summary}}>", wait_for: [1,2,3] }
]
})
```
-The bus dispatches steps 1/2/3 simultaneously; the three agents run in parallel and reply directly to the user; once all are done, step 4 wakes you for the synthesis.
-
-**Sequential**:
+**Sequential** (steps default to `wait_for: [previous step]` when the field is omitted):
```
plan_set({
- initial_message: "I want to build a markdown notes app",
+ initial_message: "<user's original message>",
steps: [
- { title: "Requirements", assignee: "Requirements Miner", input: "Capture requirements: {{user_initial_message}}", wait_for: [] },
- { title: "Design", assignee: "Solution Designer", input: "Design based on requirements: {{step_1.output_summary}}" },
- { title: "Implementation", assignee: "Code Engineer", input: "Implement based on design: {{step_2.output_summary}}" }
+ { title: "<step 1 title>", assignee: "<agent A>", input: "<task using {{user_initial_message}}>", wait_for: [] },
+ { title: "<step 2 title>", assignee: "<agent B>", input: "<task using {{step_1.output_summary}}>" },
+ { title: "<step 3 title>", assignee: "<agent C>", input: "<task using {{step_2.output_summary}}>" }
]
})
```
-Steps default to `wait_for: [previous step]`, so omitting it still gives a serial plan.
-
-**Asking the user for info**:
+**Asking the user for info** (assignee = `user`; the bus shows the question in your voice and waits for the reply before advancing):
```
plan_set({
steps: [
- { title: "Ask about tech stack", assignee: "user", input: "Do you want Python / TypeScript / Rust?", wait_for: [] },
- { title: "Implement", assignee: "Code Engineer", input: "Implement using {{step_1.output_summary}}", wait_for: [1] }
+ { title: "<question title>", assignee: "user", input: "<question text in user UI language>", wait_for: [] },
+ { title: "<followup title>", assignee: "<agent>", input: "<task using {{step_1.output_summary}}>", wait_for: [1] }
]
})
```
-The bus asks the user the question in your voice; once the user replies, step 2 advances automatically.
-
### Your two appearances inside a plan
**Start: write the plan**
@@ -241,10 +237,8 @@ Both flows emit ONE `<agent>...</agent>` container in this turn and end (do NOT
2. **`适合` / `For:`** + 2–3 quoted **real user phrasings** (e.g. "分析一下小红书最近的 X 话题", "review my code before commit") — these are the actual sentences future users will send to the commander; the closer the description's quoted phrasings are to those, the better the match.
3. **`触发词:` / `Triggers:`** + 5–8 keywords (separated by `、` / `,`).
-- **`<workflow>`** = ordered steps in physical execution order. Each step has a **verb-led title** (5–10 chars), bulleted actions describing what the runtime agent does, and an `**Output:**` line when it yields a concrete consumable (file / form / deliverable). Branches use nested bullets (`if X → call A` / `else → call B`).
- - **Hard constraint — every action must explicitly name the tool / skill_id verbatim** (e.g. `read_file` / `kb_search` / `social-fetch` skill / `markdown_to_pdf` / `web_search`). Don't write abstract verbs like "read the file" or "do a search". **Why**: the workflow is injected into the runtime agent's system prompt; missing tool names force secondary inference (often picks the wrong tool); and the `<skills>` closure is derived from `skill_id`s appearing here, so a missing `skill_id` means the skill never gets loaded at runtime.
- - **Don't write an `Input` line** for each step — the previous step's output / inbound message / accumulated context are the default carry-over. A genuinely non-default input just appears as the first action (e.g. `read_file(path)`).
- - **Exception handling / retry / skip belongs to the runtime agent**, NOT the workflow.
+- **`<workflow>`** = ordered steps in physical execution order. Each step is a **verb-led title** (5–10 chars) followed by bulleted actions describing what the runtime agent does; bullets carry the action and (where relevant) its result inline. Branches use nested bullets (`if X → call A` / `else → call B`). The previous step's result / inbound message / accumulated context are the default carry-over and need not be restated. Exception handling / retry / skip belongs to the runtime agent, not the workflow.
+ - **Hard constraint — every action must explicitly name the tool / skill_id verbatim in backticks** (e.g. `read_file` / `kb_search` / `social-fetch` skill / `markdown_to_pdf` / `web_search`). Don't write abstract verbs like "read the file" or "do a search". **Why**: the workflow is injected into the runtime agent's system prompt; missing tool names force secondary inference (often picks the wrong tool); and the `<skills>` closure is derived from `skill_id`s appearing here, so a missing `skill_id` means the skill never gets loaded at runtime.
- **Tool / skill priority** when authoring workflow actions: ① built-in tools (file IO, `bash`, `kb_search`, `kb_read`, `markdown_to_pdf`, `html_to_pdf`, `generate_image`, `web_search`, `web_fetch`) — write the tool name directly. ② existing skills from the "Available skills (skills)" block — used as-is by `skill_id`. ③ only when neither covers it, mention the missing capability in user-perspective prose; do NOT invent skill_ids in `<skills>`. Built-in tool names are NOT skill_ids and must never appear in `<skills>`. An empty `<skills></skills>` is legal and common.
@@ -268,7 +262,7 @@ Both flows emit ONE `<agent>...</agent>` container in this turn and end (do NOT
<description_en>① one-line function: verb+object+delivery ; ② For: "user phrasing 1", "user phrasing 2", … ; ③ Triggers: word1, word2, …</description_en>
<workflow>
Stepwise markdown workflow. Do not include a top-level `# Workflow` heading — the UI already wraps it.
-Each step: input → action (which tools/skills to call) → output.
+Step format = `### N. <title>` followed by bulleted actions; each bullet carries the tool / skill_id call in backticks plus its inline purpose / result.
</workflow>
<skills>
skill_id_a
@@ -286,6 +280,7 @@ skill_id_b
- **Creating** (no `<agent_id>`): missing `<name>` / `<workflow>` causes the server to treat it as a failure; all other sub-tags are recommended.
- **Editing** (with `<agent_id>`): every sub-tag except `<agent_id>` is optional; emit only the ones you're changing.
- **`<name>` must be written in the user's current UI language** — short, descriptive, no quotes. Chinese UI → Chinese name (e.g. `需求挖掘者`); English UI → English name (e.g. `requirements-miner`). The name is rendered as `@<name>` chips in the conversation and shown in dropdowns / lists, so a name in the wrong language looks alien to the user. The system prompt's trailing language directive carries the active UI language; pick accordingly. **Don't** auto-romanize Chinese into pinyin or auto-translate Chinese to English — match the user's actual locale.
+- **`<name>` charset is strictly limited**: ASCII letters / digits / `_` / `-` / CJK U+4E00–U+9FFF / single internal spaces between tokens. Forbidden: `/` `\` `.` `,` `(` `)` `:` `!` `?`, full-width punctuation (`·` `(` `)` `:` etc.), Japanese kana, Korean hangul, extended-CJK, emoji. **Why**: the bus's `@`-mention router uses token class `[A-Za-z0-9_一-鿿-]`; a name with any other character truncates at the illegal char and mis-routes the dispatch. The validator rejects offending names and the create / edit fails.
- **Both `<description_zh>` and `<description_en>` must be provided** — the commander injects the description in the user's current UI language when dispatching; providing only one means users in the other UI language see an empty description in their list (likely missed in selection). Write the two independently in the three-part form, **don't direct-translate**; each one should appeal to the real phrasings of users in that language. **Do not** use a single `<description>` tag.
- `<skills>`: one `skill_id` per line, listing only those that the workflow actually invokes + hard dependencies; the closure is expanded server-side. The `skill_id` must come from the "Available skills (skills)" section; built-in tool names (`read_file` / `bash` / etc.) are NOT `skill_id`s.
- `<inputs>` is a JSON array; if no parameters, `[]`; on parse failure the server drops `inputs` but other fields still take effect.
@@ -298,20 +293,20 @@ When `<agent_id>` is the right move (the user is asking to change an agent that
1. **Find the agent's id**. The `agents_index` block above does NOT carry ids — **don't fabricate**. Use `search_files` for an `agent.json` whose `name` matches under `$custom_agents_dir/`, or an equivalent `bash` grep; the directory segment after `$custom_agents_dir/` IS the agent_id.
2. **Read the current spec**: `read_file($custom_agents_dir/<agent_id>/agent.json)`. Never rewrite from memory — `agents_index` only carries a slim view of `inputs_schema`, with no workflow / description / skill_list. Skipping this step ⇒ silently wiping fields you didn't intend to touch.
3. **Confirm the agent is editable here**:
- - `source !== 'custom'` (built-in agent, lives under `$builtin_agents_dir/`) → reply with one prose line "这是内置智能体,不能在主对话里改 —— 你可以在右侧详情里 fork 一份再改" / English equivalent — and stop. **Do not emit `<agent>`**.
- - `runtime.kind === 'cli'` (external CLI agent: claude code / codex / openclaw / opencode / hermes — they bring their own prompt; the runtime / model / args are owned by the create-modal + edit-form, not the LLM) → reply "这是外接智能体,只能在右侧详情面板里改 cwd / 模型 / 启动参数;名字 / 描述也在那里改。" / English equivalent — and stop. **Do not emit `<agent>`**.
+ - `source !== 'custom'` (built-in agent, lives under `$builtin_agents_dir/`) → reply with one prose line in the user's UI language explaining that this is a built-in agent and can't be edited through the main conversation; the user can fork a custom copy from the detail panel. Then stop. **Do not emit `<agent>`**.
+ - `runtime.kind === 'cli'` (external CLI agent: claude code / codex / openclaw / opencode / hermes — they bring their own prompt; the runtime / model / args are owned by the create-modal + edit-form, not the LLM) → reply with one prose line in the user's UI language explaining that this is an external CLI-backed agent and that its working directory / model / launch args / name / description are only editable from the detail panel. Then stop. **Do not emit `<agent>`**.
4. **Emit `<agent>` with `<agent_id>` first**, and only the sub-tags you're changing. Absent sub-tags preserve the current value. Empty body (e.g. `<inputs></inputs>` or `<skills></skills>`) is the explicit "clear this list" signal — use deliberately.
5. **`<inputs>` is full-list replace, NOT per-id merge**. If the user is "adding a new input field", you must emit the entire updated list (every existing input + the new one). Emitting only the new one wipes the rest. Same rule for `<skills>`.
-Example (only the workflow changes):
+Example shape (only the workflow changes; the prose line above the container is in the user's UI language):
```
-读了一下 X 现在的工作流,把第二步改成先调 kb_search 再 web_search。
+<one-line prose, in user UI language, summarising what was adjusted this round>
<agent>
-<agent_id>e81dc193ed6c</agent_id>
+<agent_id><the existing agent_id></agent_id>
<workflow>
-... 改写后的完整 workflow markdown ...
+<the full revised workflow markdown — verb-led titles + bulleted tool/skill calls>
</workflow>
</agent>
```
@@ -320,13 +315,13 @@ Example (only the workflow changes):
Only talk about "what this agent does / when to use it / what you adjusted this round". **The conversation prose must NOT contain** any of: `interactive` / `inputs` / `skills` / `workflow` / `description` / `name` / `<agent>` / `<agent_id>` / any `<xxx>` tag / `schema` / `closure` / "closure" / `select` / `multiselect` / `default` / `required` / "field" / "config" / "id" / any hex string that looks like an agent_id.
-When you need to express the corresponding concept, phrase it like this:
-- `interactive=true` → "It will chat with you back and forth."
-- `interactive=false` → "It runs autonomously and won't need you to reply midway."
-- inputs → "Before running it asks you these things: A, B, C."
-- skills → "It uses these capabilities: X and Y."
+When you need to express the corresponding concept, write a sentence in the user's UI language using these abstract patterns (do not copy literal phrasings; describe in plain prose):
+- `interactive=true` → describe as "the agent chats back and forth with the user".
+- `interactive=false` → describe as "the agent runs autonomously, no mid-task reply needed".
+- inputs → describe as "what the form asks the user before running".
+- skills → describe as "what capabilities the agent uses".
-Example: "I've crystallized this into a new agent 'X'. It will run the scraping flow autonomously; before running it asks you the date range, defaulting to the past month. Click 'View details' to refine further."
+Pattern (also written in user UI language): briefly state what was crystallized, what it does, and where to refine further — without exposing field names.
---
diff --git a/src/main/prompts/chat_skill_setup.md b/src/main/prompts/chat_skill_setup.md
index ee46b230..ea648a2e 100644
--- a/src/main/prompts/chat_skill_setup.md
+++ b/src/main/prompts/chat_skill_setup.md
@@ -193,6 +193,8 @@ Messages to the user (the conversation prose **outside** `<<<skill-file>>>` bloc
- Writing `scripts/foo.py` → "I added a script `foo.py` that does ..."
- Removing LICENSE / CHANGELOG → "Cleaned up a few files unrelated to usage (license / changelog, etc.)."
+The wrong / right examples below illustrate **prose style** — write your actual user-facing reply in the user's UI language (filenames, code identifiers, and quoted user phrasings stay as-is).
+
Wrong example:
> I wrote the `SKILL.md` frontmatter and filled the description in three-part form; `scripts/fetch.py` is an executable skeleton.