pi-native-output-styles 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.7.0
+
+### Changed
+
+- Rewrote the leader brief around behaviour instead of rules. It now says what a style may and may not describe, asks for the smallest set of sentences that actually change output, and decides between edit / rewrite / create instead of following a fixed flow. Review stays report-only, and the final report is three fields: what changed, the file path, whether it was verified.
+- The brief is now written in Chinese. It is still plain Markdown in `extensions/prompts/output-style-leader.md`.
+
+### Fixed
+
+- Delegation went dormant under the rewrite. Measured over live runs on the same task, the previous brief delegated 4 of 6 times; the permissive phrasing in the rewrite produced 0 of 4, including a run whose request asked for a two-file comparison. Naming a default — "多角度任务（如 review）默认拆开" — restored it: review then split into two children, with report-only and no-child-writes both still holding.
+
+## 0.6.0
+
+### Added
+
+- `/output-style config` for the two settings worth persisting. It runs from the user config file, so both apply to every session and project:
+  - `config default <style|off>` — the style new sessions start with.
+  - `config indicator <status|widget|off>` — where the active style is shown; `status` is the default.
+- Run `config` with no arguments for a dialog per setting. A bare key reads the value back, an unknown key is an error, and a run without a dialog UI prints the config instead.
+- A `widget` indicator renders the style above the editor. Every refresh writes both surfaces, so switching modes can never leave a stale badge.
+
+### Changed
+
+- `config` joins the management words in the command router. `configure this style` still routes to the agent.
+- Clearing a saved default now merges state instead of overwriting the file, so it no longer drops the indicator setting.
+
 ## 0.5.0
 
 One command, plus a bundled style and an agent that maintains styles.

package/README.md

@@ -41,7 +41,17 @@ Then start a **new** session. Extensions do not hot-reload.
 /output-style 创建一个适合代码 Review 的 output style
 ```
 
-The rule is one line: *a single word that names a style, `off`, or `none` is management; anything else is a request for the agent.* So `/output-style concise` activates, and `/output-style rewrite concise` asks. To review a style whose name you would otherwise activate, say more than its name.
+**Configure it** — `/output-style config`:
+
+```text
+/output-style config                       interactive: pick the default and the indicator
+/output-style config default caveman       set the cross-session default
+/output-style config default off           clear it
+/output-style config indicator widget      where the active style shows
+/output-style config indicator             read one setting back
+```
+
+The rule is one line: *`config` and a single word that names a style, `off`, or `none` are management; anything else is a request for the agent.* So `/output-style concise` activates, and `/output-style rewrite concise` asks. To review a style whose name you would otherwise activate, say more than its name.
 
 While composing the command, a hint line under the editor shows both forms.
 
@@ -61,7 +71,7 @@ Review findings are specific: conflicting instructions, duplicate or unenforceab
 
 A review reports; it does not edit. The file is written only when the request asks for a change. In observed runs the agent delegated on its own when a task had several independent angles to check, and worked solo on a small single-file review.
 
-The brief lives in [`extensions/prompts/output-style-leader.md`](extensions/prompts/output-style-leader.md) and is plain Markdown — edit it without touching code.
+The brief lives in [`extensions/prompts/output-style-leader.md`](extensions/prompts/output-style-leader.md) and is plain Markdown — edit it without touching code. It is written in Chinese; translate or replace it freely.
 
 ## Bundled styles
 
@@ -97,12 +107,27 @@ Precedence:
 
 ## Config
 
+`/output-style config` holds the two things that are worth setting once. Both live in `~/.pi/agent/output-styles.json`, so they apply to every session and every project without re-stating anything.
+
+| Key | Values | What it does |
+| --- | --- | --- |
+| `default` | a style name, or `off` | The style every new session starts with. Alias: `style`. |
+| `indicator` | `status`, `widget`, `off` | Where the active style shows. Default `status`. |
+
+A bare key reads the value back. An unknown key is an error, not a silent no-op. Running `config` with no arguments opens a dialog per setting; in a non-dialog run (print or JSON mode) it prints the current config instead.
+
+The indicator is a display preference, so like the default style the personal setting wins over a project one, and a project setting applies when you have none.
+
+To set a default without opening dialogs, `/output-style <name> --save` does the same thing.
+
+## File locations
+
 | | Path |
 | --- | --- |
 | Project styles | `<repo>/.pi/output-styles/` |
 | User styles | `~/.pi/agent/output-styles/` |
 | Project default (`--project`) | `<repo>/.pi/output-styles.json` |
-| User default (`--save`) | `~/.pi/agent/output-styles.json` |
+| User default + config (`--save`, `config`) | `~/.pi/agent/output-styles.json` |
 
 Environment:
 

package/extensions/output-styles.ts

@@ -35,6 +35,7 @@ interface ExtensionUI {
   setWidget(key: string, lines: string[] | undefined, options?: { placement: "aboveEditor" | "belowEditor" }): void;
   getEditorText(): string;
   notify(message: string, type?: NotifyType): void;
+  select?(title: string, options: string[]): Promise<string | undefined>;
 }
 
 interface ExtensionContext {
@@ -143,13 +144,25 @@ export function bundledStylesDir(): string {
 
 export interface StyleState {
   active?: string;
+  indicator?: IndicatorMode;
+}
+
+/** Where the active style is shown. `status` is the default. */
+export const INDICATOR_MODES = ["status", "widget", "off"] as const;
+export type IndicatorMode = (typeof INDICATOR_MODES)[number];
+
+export function isIndicatorMode(value: unknown): value is IndicatorMode {
+  return typeof value === "string" && (INDICATOR_MODES as readonly string[]).includes(value);
 }
 
 export function readState(file: string): StyleState {
   try {
     const parsed: unknown = JSON.parse(readFileSync(file, "utf8"));
-    if (parsed && typeof parsed === "object" && "active" in parsed && typeof parsed.active === "string") {
-      return { active: parsed.active };
+    if (parsed && typeof parsed === "object") {
+      const state: StyleState = {};
+      if ("active" in parsed && typeof parsed.active === "string") state.active = parsed.active;
+      if ("indicator" in parsed && isIndicatorMode(parsed.indicator)) state.indicator = parsed.indicator;
+      return state;
     }
   } catch {
     // missing or malformed → empty
@@ -162,6 +175,13 @@ export function writeState(file: string, state: StyleState): void {
   writeFileSync(file, JSON.stringify(state, null, 2) + "\n");
 }
 
+// Merge, never replace: clearing the default must not drop the indicator
+// setting, and setting the indicator must not drop the default. A key passed
+// as undefined drops out of the JSON, which is how a key is cleared.
+export function updateState(file: string, patch: StyleState): void {
+  writeState(file, { ...readState(file), ...patch });
+}
+
 export function userStateFile(): string {
   return join(configHome(), "output-styles.json");
 }
@@ -179,6 +199,12 @@ export function resolveActiveName(
   return sessionActive ?? userState.active ?? projectState.active ?? null;
 }
 
+// The indicator is presentation, so it resolves from the same places as the
+// default style but falls back to the status bar.
+export function resolveIndicator(cwd: string): IndicatorMode {
+  return readState(userStateFile()).indicator ?? readState(projectStateFile(cwd)).indicator ?? "status";
+}
+
 const MARKER_PREFIX = "<!-- output-styles:";
 
 export function styleMarker(style: Style): string {
@@ -224,16 +250,20 @@ export function parseStyleCommandArgs(args: string): StyleCommandArgs {
   return { name, persist };
 }
 
-// One command serves both jobs, so the split has to be guessable from the
-// words alone. Rule: the request is style management only when it is empty,
-// or its single non-flag word is `off`/`none` or a style that exists. Anything
-// else is a task for the agent. `/output-style concise` activates; `/output-style
-// rewrite concise` asks the agent.
-export type StyleCommandRoute = { kind: "manage" } | { kind: "task"; request: string };
+// One command serves every job, so the split has to be guessable from the
+// words alone. Rule, in order: the request is `config` when it starts with the
+// config word; empty, `off`, `none`, or a single word naming an existing style
+// is style management; anything else is a task for the agent. `/output-style
+// concise` activates; `/output-style rewrite concise` asks the agent.
+export type StyleCommandRoute =
+  | { kind: "config"; args: string }
+  | { kind: "manage" }
+  | { kind: "task"; request: string };
 
 export function routeStyleCommand(args: string, styleNames: Iterable<string>): StyleCommandRoute {
   const request = args.trim();
   if (request.length === 0) return { kind: "manage" };
+  if (/^config(?=\s|$)/i.test(request)) return { kind: "config", args: request.replace(/^config\s*/i, "").trim() };
   const words = request.split(/\s+/).filter(t => t.length > 0 && !t.startsWith("--"));
   if (words.length === 0) return { kind: "manage" }; // flags only
   if (words.length > 1) return { kind: "task", request };
@@ -251,13 +281,14 @@ export function resolveStyleName(name: string, styleNames: Iterable<string>): st
 }
 
 const STATUS_KEY = "output-styles";
+const INDICATOR_KEY = "output-styles-indicator";
 const HINT_KEY = "output-styles-hint";
 // Persistent ghost hint shown below the editor while `/output-style` is being
 // composed. Pi only renders inline usage ghost text for builtin commands, so
 // this widget carries the same message for extension commands.
 const STYLE_HINT_LINES = [
   "/output-style <name|off> [--save] [--project]",
-  "/output-style <ask the agent to review, rewrite, or create a style>",
+  "/output-style config — default style, indicator",
 ];
 
 // Pure matcher for the widget: show the hint while the input starts with the
@@ -360,9 +391,19 @@ export function resolveActiveStyle(cwd: string, styles?: Map<string, Style>): St
   return map.get(name) ?? null;
 }
 
-function refreshStatus(ctx: ExtensionContext, style: Style | null): void {
-  if (!ctx.hasUI || typeof ctx.ui.setStatus !== "function") return;
-  ctx.ui.setStatus(STATUS_KEY, style ? `style: ${style.name}` : undefined);
+// One renderer for every call site, so switching the mode can never leave a
+// stale badge behind: both surfaces are written on every refresh, and only the
+// configured one gets text.
+function renderIndicator(ctx: ExtensionContext, style: Style | null): void {
+  if (!ctx.hasUI) return;
+  const mode = resolveIndicator(ctx.cwd);
+  const label = style ? `style: ${style.name}` : undefined;
+  if (typeof ctx.ui.setStatus === "function") {
+    ctx.ui.setStatus(STATUS_KEY, mode === "status" ? label : undefined);
+  }
+  if (typeof ctx.ui.setWidget === "function") {
+    ctx.ui.setWidget(INDICATOR_KEY, mode === "widget" && label ? [label] : undefined, { placement: "aboveEditor" });
+  }
 }
 
 // The Leader brief is plain Markdown next to the extension, so its wording can
@@ -396,9 +437,104 @@ export function buildStyleTask(brief: string, cwd: string, active: Style | null,
   ].join("\n");
 }
 
+export type ConfigKey = "default" | "indicator";
+
+export interface ConfigArgs {
+  /** null means "no key given" — open the interactive flow. */
+  key: ConfigKey | null;
+  value: string;
+}
+
+const CONFIG_KEY_ALIASES: Record<string, ConfigKey> = {
+  default: "default",
+  style: "default",
+  indicator: "indicator",
+};
+
+// `null` means an unrecognised key; `{key: null}` means no key at all.
+export function parseConfigArgs(args: string): ConfigArgs | null {
+  const tokens = args.trim().split(/\s+/).filter(t => t.length > 0);
+  if (tokens.length === 0) return { key: null, value: "" };
+  const key = CONFIG_KEY_ALIASES[tokens[0].toLowerCase()];
+  if (!key) return null;
+  return { key, value: tokens.slice(1).join(" ") };
+}
+
+function describeConfig(cwd: string): string {
+  return `Default style (new sessions): ${readState(userStateFile()).active ?? "(none)"}\nStyle indicator: ${resolveIndicator(cwd)}`;
+}
+
+function applyConfigValue(key: ConfigKey, value: string, ctx: ExtensionContext, styles: Map<string, Style>): void {
+  const raw = value.trim();
+
+  if (key === "default") {
+    if (raw.length === 0) {
+      ctx.ui.notify(`Default style (new sessions): ${readState(userStateFile()).active ?? "(none)"}`, "info");
+      return;
+    }
+    if (OFF_WORDS[raw.toLowerCase()]) {
+      updateState(userStateFile(), { active: undefined });
+      ctx.ui.notify("Default style cleared. New sessions start with no style.", "info");
+      renderIndicator(ctx, resolveActiveStyle(ctx.cwd, styles));
+      return;
+    }
+    const name = resolveStyleName(raw, styles.keys());
+    if (!name) {
+      ctx.ui.notify(`Unknown style "${raw}". Available: ${[...styles.keys()].sort().join(", ") || "(none)"}`, "error");
+      return;
+    }
+    updateState(userStateFile(), { active: name });
+    ctx.ui.notify(`Default style → "${name}" for every new session and project.`, "info");
+    renderIndicator(ctx, resolveActiveStyle(ctx.cwd, styles));
+    return;
+  }
+
+  if (raw.length === 0) {
+    ctx.ui.notify(`Style indicator: ${resolveIndicator(ctx.cwd)}`, "info");
+    return;
+  }
+  if (!isIndicatorMode(raw)) {
+    ctx.ui.notify(`Indicator must be one of: ${INDICATOR_MODES.join(", ")}`, "error");
+    return;
+  }
+  updateState(userStateFile(), { indicator: raw });
+  ctx.ui.notify(`Style indicator → ${raw}`, "info");
+  renderIndicator(ctx, resolveActiveStyle(ctx.cwd, styles));
+}
+
+// Interactive path: two dialogs, then a summary. Falls back to printing when
+// the run has no dialog-capable UI (print/json modes).
+async function openConfigDialogs(ctx: ExtensionContext, styles: Map<string, Style>): Promise<void> {
+  if (typeof ctx.ui.select !== "function") {
+    ctx.ui.notify(describeConfig(ctx.cwd), "info");
+    return;
+  }
+
+  const current = readState(userStateFile()).active ?? "(none)";
+  const chosen = await ctx.ui.select(`Default output style for new sessions (now: ${current})`, [
+    "(keep current)",
+    "(none)",
+    ...[...styles.keys()].sort(),
+  ]);
+  if (chosen !== undefined && chosen !== "(keep current)") {
+    updateState(userStateFile(), { active: chosen === "(none)" ? undefined : chosen });
+  }
+
+  const mode = await ctx.ui.select(`Style indicator (now: ${resolveIndicator(ctx.cwd)})`, [
+    "(keep current)",
+    ...INDICATOR_MODES,
+  ]);
+  if (mode !== undefined && mode !== "(keep current)" && isIndicatorMode(mode)) {
+    updateState(userStateFile(), { indicator: mode });
+  }
+
+  renderIndicator(ctx, resolveActiveStyle(ctx.cwd, styles));
+  ctx.ui.notify(`Saved.\n${describeConfig(ctx.cwd)}`, "info");
+}
+
 export default function outputStyles(pi: ExtensionAPI): void {
   pi.on("session_start", (_event, ctx) => {
-    refreshStatus(ctx, resolveActiveStyle(ctx.cwd));
+    renderIndicator(ctx, resolveActiveStyle(ctx.cwd));
     if (started || !ctx.hasUI) return;
     started = true;
     startHintPoller(ctx);
@@ -412,14 +548,14 @@ export default function outputStyles(pi: ExtensionAPI): void {
     try {
       const style = resolveActiveStyle(ctx.cwd);
       if (!style) {
-        refreshStatus(ctx, null);
+        renderIndicator(ctx, null);
         return;
       }
       // Apply first; only reflect the style in the status line once the prompt
       // was actually augmented, so a swallowed throw never advertises a style
       // the turn did not apply.
       const systemPrompt = applyStyle(event.systemPrompt ?? "", style);
-      refreshStatus(ctx, style);
+      renderIndicator(ctx, style);
       return { systemPrompt };
     } catch {
       return; // never fail a turn over a styling concern
@@ -430,10 +566,21 @@ export default function outputStyles(pi: ExtensionAPI): void {
     description:
       "Select an output style, or ask the agent to review, rewrite, or create one. Usage: /output-style <name|off|what you want> [--save] [--project]",
     getArgumentCompletions: argumentPrefix => styleCompletions(argumentPrefix, process.cwd()),
-    handler: (args, ctx) => {
+    handler: async (args, ctx) => {
       const styles = discoverStyles(styleDirs(ctx.cwd));
       const route = routeStyleCommand(args, styles.keys());
 
+      if (route.kind === "config") {
+        const parsed = parseConfigArgs(route.args);
+        if (parsed === null) {
+          ctx.ui.notify("Config keys: default <style|off>, indicator <status|widget|off>", "error");
+          return;
+        }
+        if (parsed.key === null) await openConfigDialogs(ctx, styles);
+        else applyConfigValue(parsed.key, parsed.value, ctx, styles);
+        return;
+      }
+
       if (route.kind === "task") {
         let task: string;
         try {
@@ -478,16 +625,16 @@ export default function outputStyles(pi: ExtensionAPI): void {
         let offScope = "this session";
         try {
           if (persist === "user") {
-            writeState(userStateFile(), {});
+            updateState(userStateFile(), { active: undefined });
             offScope = "cleared · user default";
           } else if (persist === "project") {
-            writeState(projectStateFile(ctx.cwd), {});
+            updateState(projectStateFile(ctx.cwd), { active: undefined });
             offScope = "cleared · project default";
           }
         } catch (err) {
           ctx.ui.notify(`Cleared for this session, but updating the saved default failed: ${String(err)}`, "warning");
         }
-        refreshStatus(ctx, null);
+        renderIndicator(ctx, null);
         ctx.ui.notify(`Output style off (${offScope}).`, "info");
         return;
       }
@@ -500,16 +647,16 @@ export default function outputStyles(pi: ExtensionAPI): void {
       let scope = "this session";
       try {
         if (persist === "user") {
-          writeState(userStateFile(), { active: name });
+          updateState(userStateFile(), { active: name });
           scope = "saved · user default";
         } else if (persist === "project") {
-          writeState(projectStateFile(ctx.cwd), { active: name });
+          updateState(projectStateFile(ctx.cwd), { active: name });
           scope = "saved · project default";
         }
       } catch (err) {
         ctx.ui.notify(`Applied for this session, but saving failed: ${String(err)}`, "warning");
       }
-      refreshStatus(ctx, styles.get(name) ?? null);
+      renderIndicator(ctx, styles.get(name) ?? null);
       ctx.ui.notify(`Output style → "${name}" (${scope}).`, "info");
     },
   });

package/extensions/prompts/output-style-leader.md

@@ -1,71 +1,103 @@
 # Output style task
 
-You own this end to end: read the request, decide what work it needs, do it,
-then verify what you produced. Finish with a short report of what changed and
-where.
+你负责完成 output style 的修改、新建或重写。
 
-## What an output style is
+## 目标
 
-A style defines **how** you behave: voice, structure, level of detail,
-interaction style. It is not a home for project architecture, coding rules,
-domain knowledge, tooling conventions, or repo facts. Anything like that is a
-responsibility-boundary bug: drop it, or say where it belongs instead.
+先理解用户真正想改变的**输出行为**，再决定怎么改。
 
-## Delegation
+Output style 只描述：
 
-Decide for yourself whether the task needs other agents. Delegate only when
-independent angles genuinely improve the result. A review is the usual case:
-prompt quality, responsibility boundaries, and conflicts/redundancy are worth
-splitting. Use the `subagent` tool when it is available, and run the children
-in one workflow call. If it is not available, do the analysis yourself.
-Children report findings back to you and never write files. You do the final
-write and the final summary — never hand the file off.
+* 怎么说
+* 怎么组织答案
+* 信息详细到什么程度
+* 如何与用户互动
 
-## Reviewing
+不要把项目架构、编码规范、领域知识、工具使用规则、仓库事实等塞进 style。
 
-Review means report, not edit. Do not change the file unless the request also
-asks for the change; offer the fix instead.
+## 工作方式
 
-Name each finding specifically: what is wrong, what it costs, and the fix.
-Look for:
+先检查：
 
-- instructions that conflict with each other
-- duplicate, dead, or unenforceable rules
-- vague wording that cannot be acted on
-- over-constraining the model
-- content that belongs to another concern
-- AI-slop voice: inflated claims, filler, ceremony
-- rules that are hard to follow while actually working
+* 用户当前使用的 style
+* 相关已有 styles
+* 用户描述的实际问题
+* 必要时查看相关文档、实现或进行 research
 
-No praise padding, and do not restate the style back at the user.
+不要为了“完整”而 research。只有现有信息不足以判断正确做法时才 research。
 
-## Rewriting
+然后决定是：
 
-Keep what works, delete what does not, add only what is missing. Fewer sharp
-rules beat more rules. Do not add text to look thorough, and do not quietly
-widen the scope.
+* **修改**：保留有效部分，删除无效或造成问题的部分
+* **重写**：当现有 style 的方向已经不对时重新设计
+* **新建**：从目标出发写一个最小可用的 style
 
-## Creating
+每次先判断需不需要多方视角：需要就并行分给子 agent（有 `subagent` 工具就用），review 这类要多角度查的任务默认拆开；不需要就自己做。子 agent 只报告不写文件，最终文件由你自己写。
 
-Write the smallest style that achieves the goal. `name` is lowercase
-kebab-case; `description` is one line and shows up in `/style`.
+核心原则：
 
-## File format
+> 少写规则，直接描述期望的行为。
 
-    ---
-    name: <kebab-case>
-    description: <one line>
-    ---
-    <style body>
+避免：
 
-## Where to write
+* 提示词腔
+* AI 味
+* 解释规则为什么存在
+* 重复表达
+* 过度约束
+* 模糊但听起来正确的话
+* 为了显得专业而增加细节
 
-Default to the project directory. Write to the user directory only when asked
-for personal or global. Never edit a style under a package install path — those
-are read-only bundled styles; copy one out instead.
+如果一句话不能明显改变模型的输出，就不要写。
 
-## Before you finish
+## Review
 
-- Re-read what you wrote: frontmatter plus body, nothing else.
-- Confirm the file parses and the `name` matches what `/style <name>` expects.
-- State the path you wrote and what changed.
+如果用户要求审核，只报告问题，不直接修改。
+
+重点找：
+
+* 会导致输出变差的规则
+* 相互冲突的规则
+* 重复或无效规则
+* 难以执行的规则
+* 不属于 output style 的内容
+* 让回答变得啰嗦、机械、难读的规则
+
+每个问题说明：
+
+**问题 → 影响 → 建议**
+
+不要写赞美，也不要重新解释整个 style。
+
+## Style 格式
+
+```md
+---
+name: <lowercase-kebab-case>
+description: <one line>
+---
+<style body>
+```
+
+description 用一句话说明这个 style 会带来什么输出变化。
+
+style body 应尽可能短。
+
+## 完成前
+
+重新阅读最终文件，从实际使用角度判断：
+
+> 如果模型只看到这个 style，它真的会因此产生不同的、更符合目标的输出吗？
+
+确认：
+
+* frontmatter 正确
+* name 与文件名一致
+* style 可以正常加载
+* 内容没有明显重复、冲突或越界
+
+最后只报告：
+
+* 做了什么
+* 文件路径
+* 是否完成验证

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-native-output-styles",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Named, swappable system-prompt styles for Pi — live /style switcher with native .pi/ directory support.",
   "keywords": [
     "pi-package",