pi-incarnate 0.1.0 → 0.2.0

package/src/character-loader.ts

@@ -41,6 +41,13 @@ export interface CharacterDiscovery {
   issues: CharacterIssue[];
 }
 
+export interface ParsedCharacterCard {
+  markdown: string;
+  name: string;
+  sections: Readonly<Record<RequiredSection, string>>;
+  mood: MoodConfig;
+}
+
 export class CharacterLoadError extends Error {
   readonly code: CharacterIssueCode;
   readonly path: string;
@@ -94,6 +101,19 @@ function parseCard(markdown: string, cardPath: string): Pick<Character, "name" |
   };
 }
 
+export function parseCharacterCard(markdown: string, cardPath = "CHARACTER.md"): ParsedCharacterCard {
+  const normalized = markdown.replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n").trim();
+  const parsed = parseCard(normalized, cardPath);
+  let mood: MoodConfig;
+  try {
+    mood = parseMoodConfig(normalized);
+  } catch (error) {
+    const message = error instanceof MoodConfigError ? error.message : "Invalid Current Mood section";
+    throw new CharacterLoadError("invalid-card", message, cardPath);
+  }
+  return { markdown: normalized, mood, ...parsed };
+}
+
 export function isCharacterId(value: string): boolean {
   return CHARACTER_ID_PATTERN.test(value);
 }
@@ -123,33 +143,37 @@ export async function loadCharacter(charactersRoot: string, id: string): Promise
   }
 
   const cardPath = join(characterDirectory, "CHARACTER.md");
+  let canonicalCardPath: string;
   try {
     if (!(await stat(characterDirectory)).isDirectory()) {
       throw new CharacterLoadError("invalid-directory", `Character path is not a directory: ${id}`, characterDirectory);
     }
+    const cardInfo = await lstat(cardPath);
+    if (!cardInfo.isFile() || cardInfo.isSymbolicLink()) {
+      throw new CharacterLoadError("outside-root", `CHARACTER.md must be a regular file: ${id}`, cardPath);
+    }
+    canonicalCardPath = await realpath(cardPath);
+    if (!isWithin(characterDirectory, canonicalCardPath) || dirname(canonicalCardPath) !== characterDirectory) {
+      throw new CharacterLoadError("outside-root", `CHARACTER.md escapes the character directory: ${id}`, cardPath);
+    }
   } catch (error) {
     if (error instanceof CharacterLoadError) throw error;
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      throw new CharacterLoadError("missing-card", `Missing or unreadable CHARACTER.md for: ${id}`, cardPath);
+    }
     throw new CharacterLoadError("unreadable", `Cannot inspect character directory: ${id}`, characterDirectory);
   }
 
   let buffer: Buffer;
   try {
-    buffer = await readFile(cardPath);
+    buffer = await readFile(canonicalCardPath);
   } catch {
     throw new CharacterLoadError("missing-card", `Missing or unreadable CHARACTER.md for: ${id}`, cardPath);
   }
 
-  const markdown = decodeUtf8(buffer, cardPath).replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n").trim();
-  const parsed = parseCard(markdown, cardPath);
-  let mood: MoodConfig;
-  try {
-    mood = parseMoodConfig(markdown);
-  } catch (error) {
-    const message = error instanceof MoodConfigError ? error.message : "Invalid Current Mood section";
-    throw new CharacterLoadError("invalid-card", message, cardPath);
-  }
-  const forms = await resolveFormReferences(characterDirectory, markdown);
-  return { id, directory: characterDirectory, cardPath, markdown, mood, forms, ...parsed };
+  const parsed = parseCharacterCard(decodeUtf8(buffer, cardPath), cardPath);
+  const forms = await resolveFormReferences(characterDirectory, parsed.markdown);
+  return { id, directory: characterDirectory, cardPath, forms, ...parsed };
 }
 
 export async function discoverCharacters(charactersRoot: string): Promise<CharacterDiscovery> {

package/src/character-section-editor.ts

@@ -0,0 +1,120 @@
+import { CharacterEditError } from "./character-editor.ts";
+
+export const GUIDED_CHARACTER_SECTIONS = [
+  "Identity",
+  "Personality",
+  "Speech Style",
+  "Behavior",
+  "Current Mood",
+  "Tools and Forms",
+] as const;
+
+export type GuidedCharacterSection = (typeof GUIDED_CHARACTER_SECTIONS)[number];
+
+export interface CharacterSectionDraft {
+  content: string;
+  exists: boolean;
+}
+
+interface HeadingLocation {
+  level: number;
+  line: number;
+  name: string;
+}
+
+function normalizedLines(markdown: string): string[] {
+  return markdown.replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n").split("\n");
+}
+
+function headings(lines: readonly string[]): HeadingLocation[] {
+  const locations: HeadingLocation[] = [];
+  let fence: { marker: string; length: number } | undefined;
+  lines.forEach((line, index) => {
+    const fenceMatch = line.match(/^\s*(`{3,}|~{3,})/);
+    if (fenceMatch) {
+      const marker = fenceMatch[1]![0]!;
+      if (!fence) fence = { marker, length: fenceMatch[1]!.length };
+      else if (fence.marker === marker && fenceMatch[1]!.length >= fence.length) fence = undefined;
+      return;
+    }
+    if (fence) return;
+    const match = line.match(/^(#{1,6})(?!#)\s+(.+?)(?:\s+#+)?\s*$/);
+    if (match) locations.push({ level: match[1]!.length, line: index, name: match[2]!.trim() });
+  });
+  return locations;
+}
+
+function normalizeBody(content: string): string {
+  return content.replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n").trim();
+}
+
+function finish(lines: readonly string[]): string {
+  return `${lines.join("\n").trimEnd()}\n`;
+}
+
+function sectionLocation(lines: readonly string[], name: string): { heading: HeadingLocation; endLine: number } | undefined {
+  const levelTwo = headings(lines).filter((heading) => heading.level === 2);
+  const matches = levelTwo.filter((heading) => heading.name.toLowerCase() === name.toLowerCase());
+  if (matches.length > 1) throw new CharacterEditError(`Character card contains duplicate sections: ${name}`);
+  const heading = matches[0];
+  if (!heading) return undefined;
+  const next = levelTwo.find((candidate) => candidate.line > heading.line);
+  return { heading, endLine: next?.line ?? lines.length };
+}
+
+export function readCharacterSection(markdown: string, name: GuidedCharacterSection): CharacterSectionDraft {
+  const lines = normalizedLines(markdown);
+  const location = sectionLocation(lines, name);
+  if (!location) return { content: "", exists: false };
+  return {
+    content: lines.slice(location.heading.line + 1, location.endLine).join("\n").trim(),
+    exists: true,
+  };
+}
+
+export function updateCharacterSection(
+  markdown: string,
+  name: GuidedCharacterSection,
+  content: string,
+): string {
+  const lines = normalizedLines(markdown);
+  const location = sectionLocation(lines, name);
+  const body = normalizeBody(content);
+  if (headings(body.split("\n")).some((heading) => heading.level <= 2)) {
+    throw new CharacterEditError("Section content cannot contain level-one or level-two headings; use the complete card editor");
+  }
+  if (!location) {
+    const existing = lines.join("\n").trimEnd();
+    return `${existing}\n\n## ${name}\n\n${body}${body ? "\n" : ""}`;
+  }
+  const replacement = body ? ["", ...body.split("\n"), ""] : [""];
+  return finish([
+    ...lines.slice(0, location.heading.line + 1),
+    ...replacement,
+    ...lines.slice(location.endLine),
+  ]);
+}
+
+export function updateCharacterName(markdown: string, name: string): string {
+  const normalizedName = name.trim().replace(/\s*[\r\n]+\s*/g, " ");
+  if (!normalizedName) throw new CharacterEditError("Character name must not be empty");
+  if (normalizedName.length > 120) throw new CharacterEditError("Character name must not exceed 120 characters");
+  if (/\s#+$/.test(normalizedName)) {
+    throw new CharacterEditError("Character name must not end with Markdown closing hashes");
+  }
+  const lines = normalizedLines(markdown);
+  const firstHeading = headings(lines).find((heading) => heading.level === 1);
+  if (!firstHeading) throw new CharacterEditError("CHARACTER.md must contain a level-one character name");
+  lines[firstHeading.line] = `# ${normalizedName}`;
+  return finish(lines);
+}
+
+export function sectionStarter(name: GuidedCharacterSection): string {
+  if (name === "Current Mood") {
+    return "Default: normal\n\n### normal\n\n保持角色的常态表达方式。";
+  }
+  if (name === "Tools and Forms") {
+    return "- 偏好表名称：`forms/preferences.md`";
+  }
+  return "";
+}

package/src/commands.ts

@@ -1,26 +1,36 @@
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 
-import { CharacterLoadError, discoverCharacters, loadCharacter } from "./character-loader.ts";
+import {
+  characterSource,
+  discoverCharacterCatalog,
+  loadCatalogCharacter,
+  type CharacterLocations,
+} from "./character-catalog.ts";
+import { CharacterLoadError } from "./character-loader.ts";
+import { openIncarnateMenu } from "./menu.ts";
+import type { AvatarMode } from "./session-state.ts";
 import type { IncarnateSessionState } from "./session-state.ts";
 
 export interface IncarnateCommandDependencies {
   charactersRoot: string;
+  personalCharactersRoot?: string;
   state: IncarnateSessionState;
   onStateChange?: (ctx: ExtensionCommandContext) => Promise<void> | void;
 }
 
 const USAGE =
-  "Usage: /incarnate list | use <character-id> | off | status | mood <preset> | avatar on|off";
+  "Usage: /incarnate list | use <character-id> | off | status | mood <preset> | avatar auto|full|compact|off";
 
 function notifyError(ctx: ExtensionCommandContext, message: string): void {
   ctx.ui.notify(message, "error");
 }
 
 export function registerIncarnateCommand(pi: ExtensionAPI, dependencies: IncarnateCommandDependencies): void {
-  const { charactersRoot, state, onStateChange } = dependencies;
+  const { charactersRoot, personalCharactersRoot, state, onStateChange } = dependencies;
+  const locations: CharacterLocations = { builtInRoot: charactersRoot, personalRoot: personalCharactersRoot };
 
   pi.registerCommand("incarnate", {
-    description: "List, enable, disable, or inspect character personas",
+    description: "Open the character menu or manage personas with subcommands",
     getArgumentCompletions: async (prefix) => {
       const [subcommand = "", argument = ""] = prefix.trimStart().split(/\s+/, 2);
       if (!prefix.trimStart().includes(" ")) {
@@ -29,7 +39,7 @@ export function registerIncarnateCommand(pi: ExtensionAPI, dependencies: Incarna
           .map((value) => ({ value, label: value }));
       }
       if (subcommand === "avatar") {
-        const matches = ["on", "off"]
+        const matches = ["auto", "full", "compact", "off", "on"]
           .filter((value) => value.startsWith(argument))
           .map((value) => ({ value: `avatar ${value}`, label: value }));
         return matches.length > 0 ? matches : null;
@@ -41,22 +51,31 @@ export function registerIncarnateCommand(pi: ExtensionAPI, dependencies: Incarna
         return matches.length > 0 ? matches : null;
       }
       if (subcommand !== "use") return null;
-      const { characters } = await discoverCharacters(charactersRoot);
-      const matches = characters
-        .filter((character) => character.id.startsWith(argument))
-        .map((character) => ({ value: `use ${character.id}`, label: character.id, description: character.name }));
+      const { entries } = await discoverCharacterCatalog(locations);
+      const matches = entries
+        .filter(({ character }) => character.id.startsWith(argument))
+        .map(({ character }) => ({ value: `use ${character.id}`, label: character.id, description: character.name }));
       return matches.length > 0 ? matches : null;
     },
     handler: async (args, ctx) => {
       const [subcommand = "", id, ...extra] = args.trim().split(/\s+/).filter(Boolean);
 
+      if (!subcommand) {
+        if (ctx.hasUI) {
+          await openIncarnateMenu(ctx, { locations, state, onStateChange });
+        } else {
+          ctx.ui.notify(USAGE, "info");
+        }
+        return;
+      }
+
       if (subcommand === "list" && !id) {
-        const { characters, issues } = await discoverCharacters(charactersRoot);
-        if (characters.length === 0) {
-          ctx.ui.notify(`No valid characters found in ${charactersRoot}`, "warning");
+        const { entries, issues } = await discoverCharacterCatalog(locations);
+        if (entries.length === 0) {
+          ctx.ui.notify("No valid characters found", "warning");
         } else {
-          const list = characters
-            .map((character) => `${character.id} — ${character.name}${state.activeCharacter?.id === character.id ? " (active)" : ""}`)
+          const list = entries
+            .map(({ character, source }) => `${character.id} — ${character.name}${state.activeCharacter?.id === character.id ? " (active)" : ""} [${source}]`)
             .join("\n");
           ctx.ui.notify(list, "info");
         }
@@ -68,7 +87,7 @@ export function registerIncarnateCommand(pi: ExtensionAPI, dependencies: Incarna
 
       if (subcommand === "use" && id && extra.length === 0) {
         try {
-          const character = await loadCharacter(charactersRoot, id);
+          const { character } = await loadCatalogCharacter(locations, id);
           state.activate(character);
           await onStateChange?.(ctx);
           ctx.ui.notify(`Character enabled: ${character.name} (${character.id})`, "info");
@@ -91,8 +110,8 @@ export function registerIncarnateCommand(pi: ExtensionAPI, dependencies: Incarna
         const active = state.activeCharacter;
         ctx.ui.notify(
           active
-            ? `Active character: ${active.name} (${active.id})\nMood: ${state.currentMood ?? "none"}\nAvatar: ${state.avatarEnabled ? "on" : "off"}\nForms: ${active.forms.filter((form) => form.status === "available").length}/${active.forms.length} available\nCard: ${active.cardPath}`
-            : `Character mode: off\nAvatar: ${state.avatarEnabled ? "on" : "off"}`,
+            ? `Active character: ${active.name} (${active.id})\nSource: ${characterSource(active, locations)}\nMood: ${state.currentMood ?? "none"}\nAvatar: ${state.avatarMode}\nForms: ${active.forms.filter((form) => form.status === "available").length}/${active.forms.length} available\nCard: ${active.cardPath}`
+            : `Character mode: off\nAvatar: ${state.avatarMode}`,
           "info",
         );
         return;
@@ -115,10 +134,16 @@ export function registerIncarnateCommand(pi: ExtensionAPI, dependencies: Incarna
         return;
       }
 
-      if (subcommand === "avatar" && (id === "on" || id === "off") && extra.length === 0) {
-        state.setAvatarEnabled(id === "on");
+      if (
+        subcommand === "avatar" &&
+        id &&
+        ["auto", "full", "compact", "off", "on"].includes(id) &&
+        extra.length === 0
+      ) {
+        const mode: AvatarMode = id === "on" ? "auto" : (id as AvatarMode);
+        state.setAvatarMode(mode);
         await onStateChange?.(ctx);
-        ctx.ui.notify(`Avatar: ${id}`, "info");
+        ctx.ui.notify(`Avatar: ${mode}`, "info");
         return;
       }
 

package/src/form-editor.ts

@@ -0,0 +1,115 @@
+import { lstat, mkdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, extname, isAbsolute, relative, resolve, sep } from "node:path";
+
+import { CharacterEditError, resolvePersonalDirectory } from "./character-editor.ts";
+
+export const FORM_MAX_BYTES = 256 * 1024;
+
+export interface FormDraft {
+  path: string;
+  content: string;
+  exists: boolean;
+}
+
+function isWithin(parent: string, child: string): boolean {
+  const pathFromParent = relative(parent, child);
+  return pathFromParent !== ".." && !pathFromParent.startsWith(`..${sep}`) && !isAbsolute(pathFromParent);
+}
+
+function formTarget(characterDirectory: string, declaredPath: string): string {
+  if (!declaredPath || isAbsolute(declaredPath) || extname(declaredPath).toLowerCase() !== ".md") {
+    throw new CharacterEditError("Editable form paths must be relative .md files");
+  }
+  const target = resolve(characterDirectory, declaredPath);
+  if (!isWithin(characterDirectory, target) || target === characterDirectory) {
+    throw new CharacterEditError(`Form path escapes the character directory: ${declaredPath}`);
+  }
+  return target;
+}
+
+function formTemplate(label: string): string {
+  return `# ${label}\n\n在这里记录希望角色按需读取的偏好信息。\n`;
+}
+
+async function inspectExistingForm(characterDirectory: string, target: string): Promise<Buffer | undefined> {
+  let info;
+  try {
+    info = await lstat(target);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw new CharacterEditError(`Cannot inspect form file: ${target}`);
+  }
+  if (!info.isFile() || info.isSymbolicLink()) {
+    throw new CharacterEditError(`Form must be a regular file, not a symbolic link: ${target}`);
+  }
+  const canonicalTarget = await realpath(target);
+  if (!isWithin(characterDirectory, canonicalTarget)) {
+    throw new CharacterEditError(`Form path escapes the character directory: ${target}`);
+  }
+  if (info.size > FORM_MAX_BYTES) throw new CharacterEditError(`Form exceeds the ${FORM_MAX_BYTES}-byte editor limit: ${target}`);
+  const bytes = await readFile(canonicalTarget);
+  if (bytes.byteLength > FORM_MAX_BYTES) throw new CharacterEditError(`Form exceeds the ${FORM_MAX_BYTES}-byte editor limit: ${target}`);
+  return bytes;
+}
+
+export async function readFormDraft(
+  characterDirectory: string,
+  declaredPath: string,
+  label: string,
+): Promise<FormDraft> {
+  const canonicalDirectory = await realpath(characterDirectory);
+  const target = formTarget(canonicalDirectory, declaredPath);
+  const bytes = await inspectExistingForm(canonicalDirectory, target);
+  if (!bytes) return { path: target, content: formTemplate(label), exists: false };
+  try {
+    return { path: target, content: new TextDecoder("utf-8", { fatal: true }).decode(bytes), exists: true };
+  } catch {
+    throw new CharacterEditError(`Form is not valid UTF-8: ${target}`);
+  }
+}
+
+async function ensureSafeParent(characterDirectory: string, target: string): Promise<string> {
+  const relativeParent = relative(characterDirectory, dirname(target));
+  let current = characterDirectory;
+  for (const segment of relativeParent.split(sep).filter((value) => value && value !== ".")) {
+    current = resolve(current, segment);
+    try {
+      await mkdir(current);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    }
+    const info = await lstat(current);
+    if (!info.isDirectory() || info.isSymbolicLink()) {
+      throw new CharacterEditError(`Form parent must be a regular directory: ${current}`);
+    }
+    const canonicalCurrent = await realpath(current);
+    if (!isWithin(characterDirectory, canonicalCurrent)) {
+      throw new CharacterEditError(`Form parent escapes the character directory: ${current}`);
+    }
+  }
+  return current;
+}
+
+export async function savePersonalForm(
+  personalRoot: string,
+  id: string,
+  declaredPath: string,
+  content: string,
+): Promise<string> {
+  const characterDirectory = await resolvePersonalDirectory(personalRoot, id);
+  const target = formTarget(characterDirectory, declaredPath);
+  await inspectExistingForm(characterDirectory, target);
+  const parent = await ensureSafeParent(characterDirectory, target);
+  const normalized = `${content.replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n").trimEnd()}\n`;
+  if (Buffer.byteLength(normalized, "utf8") > FORM_MAX_BYTES) {
+    throw new CharacterEditError(`Form exceeds the ${FORM_MAX_BYTES}-byte editor limit: ${target}`);
+  }
+  const temporaryPath = resolve(parent, `.form-${crypto.randomUUID()}.tmp`);
+  try {
+    await writeFile(temporaryPath, normalized, { encoding: "utf8", flag: "wx" });
+    await rename(temporaryPath, target);
+  } finally {
+    await rm(temporaryPath, { force: true });
+  }
+  return target;
+}

package/src/markdown.ts

@@ -56,3 +56,15 @@ export function extractLevelTwoSections(markdown: string): MarkdownSection[] {
 export function findLevelTwoSection(markdown: string, name: string): string | undefined {
   return extractLevelTwoSections(markdown).find((section) => section.name.toLowerCase() === name.toLowerCase())?.content;
 }
+
+export function removeLevelTwoSection(markdown: string, name: string): string {
+  const { lines, headings } = findHeadings(markdown, 2);
+  const excluded = new Set<number>();
+  headings.forEach((heading, index) => {
+    if (heading.name.toLowerCase() !== name.toLowerCase()) return;
+    const end = headings[index + 1]?.line ?? lines.length;
+    for (let line = heading.line; line < end; line += 1) excluded.add(line);
+  });
+  if (excluded.size === 0) return markdown;
+  return lines.filter((_line, index) => !excluded.has(index)).join("\n").trim();
+}