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.

Replace streaming <<<skill-file>>> blocks with a path-aware placeholder

wytb31e631d76d3
diff --git a/src/renderer/locales/en.json b/src/renderer/locales/en.json
index 964016e3..4d6c8311 100644
--- a/src/renderer/locales/en.json
+++ b/src/renderer/locales/en.json
@@ -160,6 +160,8 @@
"chat.created_agent_chip": "Open: {name}",
"chat.create_agent_failed": "Failed to create agent: {reason}",
"chat.create_agent_streaming_placeholder": "Assembling agent config…",
+ "chat.skill_file_streaming_placeholder": "Writing {path}…",
+ "chat.skill_file_streaming_placeholder_unknown": "Writing file…",
"skills.title": "Skills",
"skills.add": "+ Add",
"skills.custom_group": "Custom",
diff --git a/src/renderer/locales/zh.json b/src/renderer/locales/zh.json
index 98376e9e..de0b1738 100644
--- a/src/renderer/locales/zh.json
+++ b/src/renderer/locales/zh.json
@@ -160,6 +160,8 @@
"chat.created_agent_chip": "查看详情:{name}",
"chat.create_agent_failed": "智能体创建失败:{reason}",
"chat.create_agent_streaming_placeholder": "正在整理智能体配置…",
+ "chat.skill_file_streaming_placeholder": "正在写入 {path}…",
+ "chat.skill_file_streaming_placeholder_unknown": "正在写入文件…",
"skills.title": "技能库",
"skills.add": "+ 添加",
"skills.custom_group": "自定义",
diff --git a/src/renderer/modules/conversation.js b/src/renderer/modules/conversation.js
index 4cbf138b..493f645a 100644
--- a/src/renderer/modules/conversation.js
+++ b/src/renderer/modules/conversation.js
@@ -3336,6 +3336,21 @@ function _stripAgentCreateBlocksForStream(buf) {
return _replaceOuterAgentBlocks(buf, _streamPlaceholderHtml('chat.create_agent_streaming_placeholder'));
}
+// `<<<skill-file path=X ... >>>` blocks (skill edit chat). Different fence
+// shape from `<agent>` (see strip-agent.js header) but same user-facing
+// contract: streaming placeholder hides the raw block + reveals the file
+// being written. The path attribute (when present) flows into the
+// localised "Writing X…" label so the placeholder is informative;
+// unattributed blocks fall back to a generic "Writing file…" label.
+function _stripSkillFileBlocksForStream(buf) {
+ return _replaceOuterSkillFileBlocks(buf, (path) => {
+ const label = path
+ ? t('chat.skill_file_streaming_placeholder', { path })
+ : t('chat.skill_file_streaming_placeholder_unknown');
+ return `\n<em class="stream-placeholder">${escapeHtml(label)}</em>\n`;
+ });
+}
+
function _stripAgentFormBlockForStream(buf) {
// Primary: XML `<agent-input-form>...</agent-input-form>` (symmetric
// with submission reply tag, token-stable). Legacy: fenced
@@ -3395,7 +3410,11 @@ function _streamingAppendFinalDelta(msg, piece) {
msg._streamRafScheduled = false;
msg._streamRafHandle = null;
const buf = msg.dataset.streamBuf || '';
- const display = _stripAgentCreateBlocksForStream(_stripAgentFormBlockForStream(buf));
+ const display = _stripAgentCreateBlocksForStream(
+ _stripAgentFormBlockForStream(
+ _stripSkillFileBlocksForStream(buf),
+ ),
+ );
finalEl.innerHTML = `<div class="markdown-body">${_renderMessageMarkdown(display)}</div>`;
};
if (typeof requestAnimationFrame === 'function') {
diff --git a/src/renderer/modules/strip-agent.js b/src/renderer/modules/strip-agent.js
index e0b8ee38..9789dcd7 100644
--- a/src/renderer/modules/strip-agent.js
+++ b/src/renderer/modules/strip-agent.js
@@ -1,15 +1,28 @@
// Pure string functions for atomic-container stripping of LLM-emitted
-// XML tags surfacing in renderer text. Three tag families share these
-// helpers via `tagName` parameter:
+// structural blocks surfacing in renderer text. Two delimiter families:
+//
+// **XML-tag containers** (handled via `tagName` parameter):
// - `<agent>` — commander create / edit container
// - `<agent-input-form>` — agent's form widget (streaming placeholder)
// - `<agent-input-submission>` — user form-reply tag (display strip)
//
-// All three need the same prose/code guard — if any of them is mentioned
-// literally inside a fenced code block or inline backtick span (e.g., a
-// protocol explanation), the literal mention must survive; the real
-// container must still be stripped/replaced atomically even when its body
-// contains backticks / fences / quotes (otherwise the prose/code split
+// **Custom-fence blocks** (`<<<delim ... \n>>>`):
+// - `<<<skill-file path=X ... >>>` — skill edit chat's file-write block
+//
+// The two families coexist because their **content shapes differ**: XML-tag
+// containers wrap structured LLM-generated prose (sub-fields like
+// `<workflow>` / `<inputs>`) and balanced-tag parsing is the natural fit;
+// the skill-file block wraps **arbitrary file content** (Python, TypeScript,
+// HTML, JSX, configs) that routinely contains naked `<` / `>` characters,
+// so a literal three-char fence is required to avoid colliding with body
+// content. Same justification as the LLM-side prompts (`chat_agent_setup.md`
+// chose XML, `chat_skill_setup.md` chose `<<<>>>`).
+//
+// Both families share the same prose/code guard — if any of them is
+// mentioned literally inside a fenced code block or inline backtick span
+// (e.g., a protocol explanation), the literal mention must survive; the
+// real container must still be stripped/replaced atomically even when its
+// body contains backticks / fences / quotes (otherwise the prose/code split
// fragments the container and the post-fragment suffix leaks past — the
// 34e27fcb / a3110e61 / follow-up cycle on `<agent>`).
//
@@ -250,12 +263,103 @@ function _replaceOuterAgentBlocks(buf, placeholder) {
// fenced block / inline backtick survives all three. After all three
// strip passes, collapse blank-line runs and trim, identical to the
// `<agent>`-only post-processing.
+// `<<<skill-file path=X attr=V\n...content...\n>>>` block ranges. Different
+// from XML-tag containers: the body is **arbitrary file content** (Python,
+// TypeScript, HTML, JSX, configs) which routinely contains naked `<` / `>`
+// characters, so we use a literal three-char fence instead of a balanced
+// XML tag — same reason `chat_skill_setup.md` chose this shape on the LLM
+// side. The opener is `<<<skill-file` followed by attribute pairs and a
+// newline; the closer is `\n>>>` (must be at line start, mirrors backend
+// `SKILL_FILE_BLOCK_RE` in `features/skills.ts`).
+//
+// Outer-context check (prose vs code segment) is shared with the tag
+// finder: a literal `<<<skill-file` mentioned inside a fenced code block
+// or inline backtick (LLM showing the protocol to a user) must NOT be
+// recognised as a real block.
+const SKILL_FILE_OPEN = '<<<skill-file';
+const SKILL_FILE_CLOSE = '\n>>>';
+
+function _findOuterSkillFileRanges(text) {
+ if (!text || text.indexOf(SKILL_FILE_OPEN) < 0) return [];
+ const segs = _splitMarkdownProseCode(text);
+ const ranges = [];
+ let pos = 0;
+ for (const seg of segs) {
+ const segStart = pos;
+ pos += seg.text.length;
+ if (seg.kind !== 'prose') continue;
+ let from = segStart;
+ while (from < pos) {
+ const last = ranges.length ? ranges[ranges.length - 1] : null;
+ if (last && from < last[1]) from = last[1];
+ if (from >= pos) break;
+ const openIdx = text.indexOf(SKILL_FILE_OPEN, from);
+ if (openIdx < 0 || openIdx >= pos) break;
+ // Mirror agent's atomic-container guarantee: once the opener is in an
+ // outer prose segment, walk to `\n>>>` regardless of what's inside
+ // (file content can contain backticks, inline code, fences, anything).
+ // Unclosed opener mid-stream → swallow rest of buffer atomically so
+ // partial file content doesn't leak into the bubble.
+ const closeIdx = text.indexOf(SKILL_FILE_CLOSE, openIdx + SKILL_FILE_OPEN.length);
+ const endPos = closeIdx < 0 ? text.length : closeIdx + SKILL_FILE_CLOSE.length;
+ ranges.push([openIdx, endPos]);
+ from = endPos;
+ }
+ }
+ return ranges;
+}
+
+function _stripOuterSkillFileBlocks(text) {
+ if (!text) return text;
+ const ranges = _findOuterSkillFileRanges(text);
+ if (!ranges.length) return text;
+ let out = '';
+ let cursor = 0;
+ for (const [s, e] of ranges) {
+ out += text.slice(cursor, s);
+ cursor = e;
+ }
+ out += text.slice(cursor);
+ return out;
+}
+
+// Pull the `path=X` attribute value out of a captured block — used by the
+// streaming placeholder so the user sees "writing <basename>…" instead of
+// a generic "writing file…". Tolerant of attribute order; quotes are not
+// expected (LLM emits `path=SKILL.md` per the spec) but stripped if found.
+function _extractSkillFilePath(blockText) {
+ const m = /\bpath=("([^"]*)"|'([^']*)'|(\S+))/.exec(blockText || '');
+ if (!m) return '';
+ return m[2] || m[3] || m[4] || '';
+}
+
+function _replaceOuterSkillFileBlocks(buf, makePlaceholder) {
+ if (!buf) return buf;
+ const ranges = _findOuterSkillFileRanges(buf);
+ if (!ranges.length) return buf;
+ let out = '';
+ let cursor = 0;
+ for (const [s, e] of ranges) {
+ out += buf.slice(cursor, s);
+ out += makePlaceholder(_extractSkillFilePath(buf.slice(s, e)));
+ cursor = e;
+ }
+ out += buf.slice(cursor);
+ return out;
+}
+
function _stripSurvivingStructuralBlocks(text) {
if (!text) return text;
let out = text;
for (const tag of ['agent', 'agent-input-form', 'agent-input-submission']) {
out = _stripOuterTagBlocks(out, tag);
}
+ // `<<<skill-file>>>` blocks: backend `extractSkillFileBlocks` strips them
+ // server-side at final-event time, but a stream aborted mid-block leaves
+ // the closing `\n>>>` absent → backend regex won't match → raw delimiters
+ // would otherwise reach the bubble. Final-time renderer safety strip
+ // covers that edge.
+ out = _stripOuterSkillFileBlocks(out);
if (out === text) return text;
return out.replace(/\n{3,}/g, '\n\n').trim();
}
@@ -270,6 +374,10 @@ if (typeof module !== 'undefined' && typeof module.exports === 'object') {
_findOuterAgentRanges,
_stripSurvivingAgentBlocks,
_replaceOuterAgentBlocks,
+ _findOuterSkillFileRanges,
+ _stripOuterSkillFileBlocks,
+ _replaceOuterSkillFileBlocks,
+ _extractSkillFilePath,
_stripSurvivingStructuralBlocks,
};
}
diff --git a/test/renderer/strip-agent.test.ts b/test/renderer/strip-agent.test.ts
index c95721c3..8ef2eb03 100644
--- a/test/renderer/strip-agent.test.ts
+++ b/test/renderer/strip-agent.test.ts
@@ -408,6 +408,214 @@ describe('_stripSurvivingStructuralBlocks (final-time safety strip)', () => {
});
});
+// --- Custom-fence blocks: `<<<skill-file path=X ... >>>` ----------------
+// Different delimiter family from XML tags above (see strip-agent.js
+// header). The skill-file block wraps **arbitrary file content** that may
+// contain naked `<` / `>` chars (Python, TypeScript, HTML, JSX, configs);
+// using XML tags would force the LLM to escape — instead the LLM-side
+// prompt (`chat_skill_setup.md`) declares a literal `<<<` / `\n>>>` fence
+// pair. The renderer must still apply the same prose/code outer-context
+// guard so a literal `<<<skill-file ...>>>` mention inside a fenced code
+// block / inline backtick (LLM explaining the protocol to the user)
+// survives, while a real block (containing arbitrary file content with
+// naked backticks / fences inside) is stripped/replaced atomically.
+
+const skill = require('../../src/renderer/modules/strip-agent.js');
+const {
+ _findOuterSkillFileRanges,
+ _stripOuterSkillFileBlocks,
+ _replaceOuterSkillFileBlocks,
+ _extractSkillFilePath,
+} = skill as {
+ _findOuterSkillFileRanges: (text: string) => Array<[number, number]>;
+ _stripOuterSkillFileBlocks: (text: string) => string;
+ _replaceOuterSkillFileBlocks: (buf: string, makePlaceholder: (path: string) => string) => string;
+ _extractSkillFilePath: (blockText: string) => string;
+};
+
+const SKILL_PH = (path: string) => `⟨SKILL:${path || '?'}⟩`;
+
+describe('skill-file — set A (real <<<skill-file>>> blocks must be replaced)', () => {
+ it('A1. plain closed block, SKILL.md frontmatter body', () => {
+ const buf = [
+ 'wrote it for you.',
+ '<<<skill-file path=SKILL.md',
+ '---',
+ 'name: foo',
+ 'description_zh: 中文',
+ 'description_en: English',
+ '---',
+ '',
+ '# body',
+ '>>>',
+ 'done.',
+ ].join('\n');
+ expect(_stripOuterSkillFileBlocks(buf)).toBe('wrote it for you.\n\ndone.');
+ expect(_replaceOuterSkillFileBlocks(buf, SKILL_PH)).toBe('wrote it for you.\n⟨SKILL:SKILL.md⟩\ndone.');
+ });
+
+ it('A2. block body contains naked `<` `>` (HTML / JSX / generic types) — atomic strip', () => {
+ // The whole reason we use a literal fence instead of XML tags: file
+ // content routinely has these chars. Strip must not be confused by them.
+ const buf = [
+ 'before',
+ '<<<skill-file path=scripts/render.tsx',
+ 'function Foo(): JSX.Element { return <div>{x < y && y > z}</div>; }',
+ 'type Bag<T> = Array<T>;',
+ '>>>',
+ 'after',
+ ].join('\n');
+ expect(_stripOuterSkillFileBlocks(buf)).toBe('before\n\nafter');
+ expect(_replaceOuterSkillFileBlocks(buf, SKILL_PH)).toBe('before\n⟨SKILL:scripts/render.tsx⟩\nafter');
+ });
+
+ it('A3. block body contains a fenced code block (markdown SKILL.md with ``` examples)', () => {
+ const buf = [
+ 'before',
+ '<<<skill-file path=SKILL.md',
+ '# Usage',
+ '```bash',
+ 'python3 scripts/run.py "topic"',
+ '```',
+ '>>>',
+ 'after',
+ ].join('\n');
+ expect(_stripOuterSkillFileBlocks(buf)).toBe('before\n\nafter');
+ expect(_replaceOuterSkillFileBlocks(buf, SKILL_PH)).toBe('before\n⟨SKILL:SKILL.md⟩\nafter');
+ });
+
+ it('A4. unclosed block mid-stream — swallow to EOF', () => {
+ const buf = 'streaming…\n<<<skill-file path=SKILL.md\n---\nname: foo\n# partial body still arr';
+ expect(_stripOuterSkillFileBlocks(buf)).toBe('streaming…\n');
+ expect(_replaceOuterSkillFileBlocks(buf, SKILL_PH)).toBe('streaming…\n⟨SKILL:SKILL.md⟩');
+ });
+
+ it('A5. two closed blocks in one buffer (e.g., SKILL.md + scripts/foo.py written same turn)', () => {
+ const buf = [
+ 'wrote two files.',
+ '<<<skill-file path=SKILL.md',
+ 'a',
+ '>>>',
+ 'and',
+ '<<<skill-file path=scripts/foo.py',
+ 'print("hi")',
+ '>>>',
+ 'done.',
+ ].join('\n');
+ expect(_stripOuterSkillFileBlocks(buf)).toBe('wrote two files.\n\nand\n\ndone.');
+ const replaced = _replaceOuterSkillFileBlocks(buf, SKILL_PH);
+ expect(replaced).toContain('⟨SKILL:SKILL.md⟩');
+ expect(replaced).toContain('⟨SKILL:scripts/foo.py⟩');
+ expect(replaced.match(/⟨SKILL:/g)?.length).toBe(2);
+ });
+});
+
+describe('skill-file — set B (literal <<<skill-file>>> mentions must survive)', () => {
+ it('B1. inside a fenced ```text block (LLM showing the protocol to the user)', () => {
+ const buf = [
+ 'Use this format to write a file:',
+ '```',
+ '<<<skill-file path=SKILL.md',
+ 'content',
+ '>>>',
+ '```',
+ 'after',
+ ].join('\n');
+ expect(_stripOuterSkillFileBlocks(buf)).toBe(buf);
+ expect(_replaceOuterSkillFileBlocks(buf, SKILL_PH)).toBe(buf);
+ });
+
+ it('B2. inside an inline backtick span', () => {
+ const buf = 'Wrap content in `<<<skill-file path=X>>>...>>>` to write it.';
+ expect(_stripOuterSkillFileBlocks(buf)).toBe(buf);
+ expect(_replaceOuterSkillFileBlocks(buf, SKILL_PH)).toBe(buf);
+ });
+
+ it('B3. inside an UNCLOSED inline backtick (mid-stream code-explanation)', () => {
+ const buf = 'You can write `<<<skill-file path=SKILL.md';
+ expect(_stripOuterSkillFileBlocks(buf)).toBe(buf);
+ expect(_replaceOuterSkillFileBlocks(buf, SKILL_PH)).toBe(buf);
+ });
+});
+
+describe('skill-file — mixed (real block + literal mention coexisting)', () => {
+ it('only the real block goes; quoted protocol example stays', () => {
+ const buf = [
+ 'Format reference:',
+ '```',
+ '<<<skill-file path=PATH',
+ 'content',
+ '>>>',
+ '```',
+ 'And here is the actual write:',
+ '<<<skill-file path=SKILL.md',
+ 'real body',
+ '>>>',
+ 'done.',
+ ].join('\n');
+ const stripped = _stripOuterSkillFileBlocks(buf);
+ expect(stripped).toContain('```');
+ expect(stripped).toContain('<<<skill-file path=PATH'); // literal mention preserved
+ expect(stripped).not.toContain('real body');
+ expect(stripped).toContain('done.');
+
+ const replaced = _replaceOuterSkillFileBlocks(buf, SKILL_PH);
+ expect(replaced).toContain('<<<skill-file path=PATH'); // literal mention preserved
+ expect(replaced).toContain('⟨SKILL:SKILL.md⟩');
+ expect(replaced).not.toContain('real body');
+ // Exactly one placeholder (only the real block; the in-fence example doesn't count).
+ expect(replaced.match(/⟨SKILL:/g)?.length).toBe(1);
+ });
+});
+
+describe('skill-file — _extractSkillFilePath', () => {
+ it('extracts the path attribute regardless of trailing attrs', () => {
+ expect(_extractSkillFilePath('<<<skill-file path=SKILL.md')).toBe('SKILL.md');
+ expect(_extractSkillFilePath('<<<skill-file path=scripts/foo.py extra=1')).toBe('scripts/foo.py');
+ });
+
+ it('tolerates quoted forms even though the spec says unquoted', () => {
+ expect(_extractSkillFilePath('<<<skill-file path="SKILL.md"')).toBe('SKILL.md');
+ expect(_extractSkillFilePath("<<<skill-file path='scripts/run.sh'")).toBe('scripts/run.sh');
+ });
+
+ it('returns empty string when path attr is missing', () => {
+ expect(_extractSkillFilePath('<<<skill-file')).toBe('');
+ expect(_extractSkillFilePath('')).toBe('');
+ });
+});
+
+describe('skill-file — _stripSurvivingStructuralBlocks final-time safety', () => {
+ it('strips a surviving <<<skill-file>>> block (backend extractor missed it: stream aborted before \\n>>>)', () => {
+ const buf = 'lead\n<<<skill-file path=SKILL.md\n# partial body never closed';
+ expect(_stripSurvivingStructuralBlocks(buf)).toBe('lead');
+ });
+
+ it('coexists with XML-tag strip: real <agent> + real <<<skill-file>>> + literal mentions', () => {
+ const buf = [
+ 'before',
+ '<agent><name>A</name></agent>',
+ 'mid',
+ '<<<skill-file path=SKILL.md',
+ 'real body',
+ '>>>',
+ 'after',
+ '```',
+ '<agent><name>QuotedExample</name></agent>', // literal in code stays
+ '<<<skill-file path=Q>>>...>>>', // inline-ish in code stays
+ '```',
+ 'end',
+ ].join('\n');
+ const out = _stripSurvivingStructuralBlocks(buf);
+ expect(out).not.toContain('<name>A</name>');
+ expect(out).not.toContain('real body');
+ expect(out).toContain('<name>QuotedExample</name>'); // protected by ``` fence
+ expect(out).toContain('mid');
+ expect(out).toContain('after');
+ expect(out).toContain('end');
+ });
+});
+
describe('_splitMarkdownProseCode sanity', () => {
it('keeps inline backtick spans as code segments', () => {
const segs = _splitMarkdownProseCode('a `b` c');