@apolloyh/apollo-agent 0.1.9 → 0.1.11

package/dist/trace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../src/trace.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAiBxD,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC,WAAW,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC,WAAW,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,iBAAiB,CAAC,EAAE,MAAM,OAAO,CAAC;IAClC;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,CAAC;AAEF,qBAAa,gBAAgB;IAiBf,OAAO,CAAC,QAAQ,CAAC,OAAO;IAhBpC,OAAO,CAAC,OAAO,CAAC,CAAiB;IACjC,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,UAAU,CAAM;IACxB,OAAO,CAAC,YAAY,CAAM;IAC1B,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,kBAAkB,CAAS;IACnC,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,kBAAkB,CAAS;IACnC,OAAO,CAAC,kBAAkB,CAAS;IACnC,OAAO,CAAC,mBAAmB,CAAM;IACjC,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,WAAW,CAAoE;gBAE1D,OAAO,EAAE,eAAe;IAErD,IAAI,IAAI,SAAS;IAIjB,SAAS,IAAI,IAAI;IAajB,UAAU,IAAI,IAAI;IAelB,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IA6H/B,OAAO,CAAC,WAAW;IAcnB,OAAO,CAAC,UAAU;IAUlB;;;OAGG;IACH,OAAO,CAAC,cAAc;IAsBtB,yEAAyE;IACzE,OAAO,CAAC,YAAY;IAepB,OAAO,CAAC,MAAM;IAUd,OAAO,CAAC,SAAS;IAUjB,OAAO,CAAC,gBAAgB;IAoBxB,OAAO,CAAC,2BAA2B;IAgBnC,OAAO,CAAC,gBAAgB;IAwCxB,OAAO,CAAC,KAAK;IAMb,OAAO,CAAC,cAAc;IAKtB,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,mBAAmB;IAa3B,OAAO,CAAC,kBAAkB;IAO1B,OAAO,CAAC,kBAAkB;IAmC1B,OAAO,CAAC,iBAAiB;IAMzB,OAAO,CAAC,gBAAgB;IAQxB,OAAO,CAAC,GAAG;CAKZ;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAOxD;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,CAO9D;AA4ED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAY1D"}
+{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../src/trace.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAiBxD,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC,WAAW,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC,WAAW,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,iBAAiB,CAAC,EAAE,MAAM,OAAO,CAAC;IAClC;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,CAAC;AAEF,qBAAa,gBAAgB;IAiBf,OAAO,CAAC,QAAQ,CAAC,OAAO;IAhBpC,OAAO,CAAC,OAAO,CAAC,CAAiB;IACjC,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,UAAU,CAAM;IACxB,OAAO,CAAC,YAAY,CAAM;IAC1B,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,kBAAkB,CAAS;IACnC,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,kBAAkB,CAAS;IACnC,OAAO,CAAC,kBAAkB,CAAS;IACnC,OAAO,CAAC,mBAAmB,CAAM;IACjC,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,WAAW,CAAoE;gBAE1D,OAAO,EAAE,eAAe;IAErD,IAAI,IAAI,SAAS;IAIjB,SAAS,IAAI,IAAI;IAajB,UAAU,IAAI,IAAI;IAelB,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IA6H/B,OAAO,CAAC,WAAW;IAcnB,OAAO,CAAC,UAAU;IAUlB;;;OAGG;IACH,OAAO,CAAC,cAAc;IAsBtB,yEAAyE;IACzE,OAAO,CAAC,YAAY;IAepB,OAAO,CAAC,MAAM;IAUd,OAAO,CAAC,SAAS;IAUjB,OAAO,CAAC,gBAAgB;IAoBxB,OAAO,CAAC,2BAA2B;IAenC,OAAO,CAAC,gBAAgB;IAwCxB,OAAO,CAAC,KAAK;IAMb,OAAO,CAAC,cAAc;IAKtB,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,mBAAmB;IAa3B,OAAO,CAAC,kBAAkB;IAO1B,OAAO,CAAC,kBAAkB;IAmC1B,OAAO,CAAC,iBAAiB;IAMzB,OAAO,CAAC,gBAAgB;IAQxB,OAAO,CAAC,GAAG;CAKZ;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAOxD;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,CAO9D;AA4ED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAY1D"}

package/dist/trace.js

@@ -280,14 +280,12 @@ export class CliTraceRenderer {
     }
     renderInteractiveToolResult(event, denied) {
         this.bullet(formatInteractiveToolResult(event.tool, event.content, event.isError, event.input), denied ? "yellow" : event.isError ? "red" : "green");
-        if (event.tool !== "shell_exec" || event.isError || event.content === "(no output)")
+        if (event.isError || event.content === "(no output)")
             return;
-        const lines = stripTerminalEscapes(event.content).split(/\r?\n/);
-        for (const [index, line] of lines.slice(0, 6).entries()) {
+        const lines = toolOutputLines(event.tool, event.content);
+        for (const [index, line] of lines.entries()) {
             this.out(`  ${this.paint(index === 0 ? "└" : " ", "gray")} ${this.paint(truncateDisplayLine(line, 140), "gray")}\n`);
         }
-        if (lines.length > 6)
-            this.out(`    ${this.paint(`… +${lines.length - 6} lines`, "gray")}\n`);
     }
     renderCodeChange(change) {
         const width = Math.max(40, Math.min(this.options.stdout?.columns ?? 120, 160));
@@ -597,6 +595,22 @@ function toolLabel(tool) {
         .map((part) => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`)
         .join(" ");
 }
+function toolOutputLines(tool, content) {
+    if (tool === "web_search") {
+        try {
+            const results = JSON.parse(content).results ?? [];
+            return results.slice(0, 5).map((result) => [result.title, result.url].filter(Boolean).join(" — "));
+        }
+        catch {
+            return [compactValue(content, 140)];
+        }
+    }
+    const lines = stripTerminalEscapes(content).split(/\r?\n/);
+    const visible = lines.slice(0, 6);
+    if (lines.length > 6)
+        visible.push(`… +${lines.length - 6} lines`);
+    return visible;
+}
 function isPermissionDenied(content) {
     return content.startsWith("Permission denied for tool ");
 }

package/dist/types.d.ts

@@ -2,6 +2,10 @@ export type JsonObject = Record<string, unknown>;
 export type ContentBlock = {
     type: "text";
     text: string;
+} | {
+    type: "thinking";
+    thinking: string;
+    signature?: string;
 } | {
     type: "tool_use";
     id: string;
@@ -59,6 +63,9 @@ export type TraceEvent = {
 } | {
     type: "assistant_delta";
     text: string;
+} | {
+    type: "thinking_delta";
+    text: string;
 } | {
     type: "llm_tool_delta";
     bytes: number;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEjD,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAE,GACjE;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtF,MAAM,MAAM,OAAO,GAAG;IACpB,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,OAAO,EAAE,MAAM,GAAG,YAAY,EAAE,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,UAAU,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEjD,MAAM,MAAM,cAAc,GAAG,aAAa,GAAG;IAC3C,IAAI,EAAE,QAAQ,CAAC;IACf,OAAO,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CAChF,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,iBAAiB,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,0DAA0D;AAC1D,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACxD;IACE,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,cAAc,GAAG,YAAY,GAAG,kBAAkB,GAAG,UAAU,CAAC;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GACD;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAC1E;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACzE;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GACtE;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,iBAAiB,CAAA;CAAE,GAC7H;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC3E;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,GAC5D;IAAE,IAAI,EAAE,0BAA0B,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GACzD;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GACtE;IAAE,IAAI,EAAE,2BAA2B,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACrD;IACE,IAAI,EAAE,YAAY,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB,GACD;IACE,IAAI,EAAE,eAAe,CAAC;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB,GACD;IACE,IAAI,EAAE,aAAa,CAAC;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB,GACD;IACE,IAAI,EAAE,iBAAiB,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAClF,GACD;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACzE;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GAC/D;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACvC;IACE,IAAI,EAAE,aAAa,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AAEN,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;AAEpD,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,UAAU,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAE9E,MAAM,MAAM,SAAS,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAElF,MAAM,MAAM,oBAAoB,GAAG;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,SAAS,CAAC;IAChB,eAAe,EAAE,gBAAgB,CAAC;IAClC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,iDAAiD;IACjD,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,OAAO,EAAE;QACP,QAAQ,EAAE,MAAM,CAAC;QACjB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,WAAW,EAAE;QACX,IAAI,EAAE,KAAK,GAAG,UAAU,GAAG,cAAc,CAAC;QAC1C,mBAAmB,EAAE,OAAO,CAAC;KAC9B,CAAC;IACF,MAAM,EAAE;QACN,WAAW,EAAE,MAAM,EAAE,CAAC;KACvB,CAAC;IACF,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC5C,MAAM,EAAE,cAAc,EAAE,CAAC;CAC1B,CAAC"}

package/docs/features-cc.md

@@ -0,0 +1,133 @@
+# Apollo 高级功能与恢复机制
+
+All state lives under **`.apollo/`** in the workspace (gitignored).
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `/plan` | Enter **Plan mode** (read-only except `.apollo/plan.md`) |
+| `/approve` | Approve plan → exit plan mode → implement |
+| `/reject` | Discard plan mode |
+| `/workflow <goal>` | Start **coordinator workflow** (研究→实现→验证→交付) |
+| `/wf` | Print workflow status bar |
+| `/save` | Persist session |
+| `/resume [id]` | Resume latest or given session |
+| `/sessions` | List sessions |
+| `/skillify name \| desc` | Turn session into `skills/<name>/SKILL.md` |
+| `/memory [query]` | List/search memories |
+| `/thought` | Expand/collapse last Thought |
+| `/status` | Mode, session id, model, token usage, Prompt Cache hit rate by request type, and cache-key diagnostics |
+
+## Goal mode
+
+Autonomous pursuit of a single goal until done (or blocked / max iterations).
+
+```text
+/goal Fix the null pointer in auth and add a regression test
+# status bar updates each iteration
+# auto-continues until GOAL_DONE / GOAL_BLOCKED / GOAL_FAILED / max
+/goal              # show status
+/goal-stop         # pause
+/goal max=8 <text> # custom max iterations (1–30)
+```
+
+Model markers:
+- `GOAL_PROGRESS:<note>`
+- `GOAL_DONE:<summary>`
+- `GOAL_BLOCKED:<what you need>`
+- `GOAL_FAILED:<reason>`
+
+Differs from `/workflow`: free-form steps, not fixed 研究→实现→验证→交付 phases.
+
+## Plan mode
+
+```text
+/plan
+# agent researches + writes .apollo/plan.md
+/approve
+# then ask: implement the plan
+```
+
+In plan mode, write tools are blocked except the plan file.
+
+## Workflow (lightweight coordinator)
+
+```text
+/workflow Fix auth null pointer and add tests
+# status bar:
+# ● 研究中 → ○ 实现中 → ○ 验证中 → ○ 交付中
+continue workflow
+```
+
+Agent is instructed to emit `PHASE_DONE:<name>:<summary>` and `WORKFLOW_DONE`.  
+Failed Task steps retry once with a corrected brief.
+
+## Hooks
+
+Copy `.apollo/hooks.example.json` → `.apollo/hooks.json`:
+
+```json
+{
+  "log": true,
+  "denyTools": ["email_send"],
+  "denyMessage": "Email blocked by hooks."
+}
+```
+
+Logging is off unless `.apollo/hooks.json` explicitly sets `log: true`. Tool calls then append to
+`.apollo/hooks.log`; sensitive fields and result content are redacted.
+
+## Memory
+
+Tools: `memory_search`, `memory_save`, `memory_list`  
+Files: `.apollo/memory/*.json`  
+Relevant memories are attached to the current user turn rather than the cache-stable system prompt. Identical memory blocks are attached once per active context and become eligible again after `/clear` or context compaction.
+
+## Prompt Cache
+
+`/status` calculates Prompt Cache hit rates only from the usage fields returned by the model provider. It reports the latest main request separately from cumulative session and per-category (`main`, `task`, `compaction`) rates. GLM is shown as implicit, provider-managed caching; Anthropic-compatible endpoints show the requested `5m` or `1h` policy.
+
+The configured `systemPrompt` comes first, followed by Apollo's built-in rules; the exact combined system prompt plus tool definitions are frozen for the lifetime of a `QueryEngine`. The Skill catalog is attached once in conversation context instead of changing the system prompt; later catalog changes are sent as additions, updates, and removals. Matched Skill instructions and memory blocks are also omitted from later turns, while Goal and Workflow modes send their full instructions once and concise state updates afterward.
+
+`/status` shows short SHA-256 fingerprints for the complete stable request prefix, cache-affecting configuration, system prompt, and tool definitions; prompt text and credentials are never included. If a request misses after a previous hit, the diagnostic reports which stable component changed or indicates that the message prefix, provider expiry, or provider behavior caused the miss. Tool results are capped at 30000 characters with both the head and tail preserved. Skill files are cached in-process and invalidated after local installation; Exa searches use a bounded 10-minute process-local cache.
+
+Tool calls use CC-style terminal feedback: streamed input shows the tool name, target path/query/command, generated size, and elapsed time as soon as those fields arrive. Execution keeps the same contextual label. New files then show a bounded, line-numbered content preview. Replacements render an `Update(path)` card with added/removed counts, old/new line numbers, surrounding context, syntax colors, and full-line red/green diff backgrounds. Approval prompts support ↑/↓, Enter, Esc, and y/n shortcuts. Display metadata is emitted only to the UI and is not added to the model's tool result.
+
+The interactive input supports ←/→, Home/End, Delete/Backspace, Ctrl-A/E/U/W, and ↑/↓ history. Ctrl-C clears a non-empty idle input before exiting. Bracketed multi-line paste is preserved as one prompt, shown in a bounded single-line viewport while editing, and collapsed to a line/character summary on submission. Structured model questions use the same arrow-key picker with a custom-answer option. During model generation or `shell_exec`, Ctrl-C aborts the current turn and returns to the input instead of terminating Apollo; an aborted turn is rolled back when no tool side effect has completed.
+
+Quiet tool results retain useful context instead of generic “completed” messages: reads and lists include their path, searches include the query and result count when available, and Bash shows the command plus a bounded six-line output preview. Long output remains in the model-visible tool result without flooding the terminal.
+
+If a streamed tool call ends with malformed or truncated JSON, Apollo automatically retries the same model request once without streaming. No tool has executed at that point, so the recovered tool call can continue safely without duplicating a write or other side effect.
+
+## Runtime recovery
+
+The main loop follows CC's staged recovery model while keeping bounded defaults:
+
+- Network failures and provider `408`, `409`, `425`, `429`, `5xx`, and `529` responses retry up to three times. Apollo honors `Retry-After` and `x-should-retry`, uses exponential backoff with jitter, and caps each wait at 30 seconds.
+- Malformed, empty, or truncated event streams retry once without streaming. If partial text was already displayed, Apollo emits only the missing suffix when the recovered response has the same prefix.
+- Provider prompt/context overflow triggers one forced semantic compaction, then retries the same pending user request with the compacted message history.
+- `max_tokens` / `max_output_tokens` responses continue automatically up to two times. Partial text remains in the transcript and in the final SDK result.
+- Tool failures remain ordinary `tool_result` errors for the model to handle. API retries occur before tool execution, so writes and other side effects are never replayed by the recovery loop.
+
+## AskUserQuestion
+
+Tool: `ask_user_question`  
+CLI prompts interactively (options as `1) …`).
+
+## Session resume
+
+- `apollo -r` and `/resume` open an interactive saved-session picker. Use ↑/↓ to move, Enter to resume, and Esc to cancel.
+- After a session is resumed, Apollo redraws its user/assistant transcript, including older turns archived by context compaction. Internal runtime context, compaction summaries, and tool-result payloads stay hidden.
+- In non-interactive terminals, the picker falls back to accepting a number or session ID.
+
+Sessions: `.apollo/sessions/<id>.json` + `latest` pointer.  
+Auto-saves after each turn, including aggregate and per-category usage counters.
+
+## Skillify
+
+```text
+/skillify auth-fix | Fix session expiry null pointer workflow
+```
+
+Creates `skills/auth-fix/SKILL.md` from recent transcript.

package/docs/guide.md

@@ -0,0 +1,250 @@
+# Apollo 使用指南
+
+本文对应 `@apolloyh/apollo-agent` 0.1.10。Apollo 是一个可在终端运行、也可通过 Node.js SDK 嵌入其他系统的个人 Agent。
+
+## 安装与升级
+
+要求 Node.js 20 或更高版本。
+
+```bash
+npm install -g @apolloyh/apollo-agent
+apollo
+```
+
+升级到最新版：
+
+```bash
+npm install -g @apolloyh/apollo-agent@latest
+```
+
+第一次运行会自动创建：
+
+- `~/.apollo/.env`：模型和搜索服务的密钥
+- `~/.apollo/config.json`：实际使用的用户级配置
+- `~/.apollo/config.example.json`：完整配置示例
+
+没有模型密钥时仍可进入交互界面；发送消息时会提示补充密钥。
+
+## 模型与搜索配置
+
+编辑 `~/.apollo/.env`：
+
+```dotenv
+ANTHROPIC_AUTH_TOKEN=your_model_token
+ANTHROPIC_BASE_URL=https://open.bigmodel.cn/api/anthropic
+ANTHROPIC_MODEL=glm-5.2
+
+# 可选：Exa 搜索
+EXA_API_KEY=your_exa_key
+
+# 可选
+# ANTHROPIC_MAX_TOKENS=131072
+# ANTHROPIC_TIMEOUT_MS=300000
+# ANTHROPIC_CACHE_TTL=5m
+```
+
+Apollo 使用 Anthropic Messages API 兼容接口。GLM/BigModel 在未显式配置时默认使用 131072 的输出上限；其他提供商默认 4096。显式设置 `ANTHROPIC_MAX_TOKENS` 始终优先。
+
+环境文件发现顺序：
+
+1. `--env-file <path>`
+2. 当前项目 `.apollo/.env`
+3. 当前项目 `.env`
+4. 用户目录 `~/.apollo/.env`
+
+密钥只应放在 env 文件或宿主进程环境变量中，不要写入 `config.json`、`APOLLO.md`、日志或会话消息。
+
+## 启动参数
+
+```bash
+apollo                         # 交互模式
+apollo "分析这个项目"          # 一次性任务
+apollo --yolo                  # 自动批准工具，readonly 仍然优先
+apollo --verbose               # 显示详细工具过程
+apollo --no-stream             # 关闭模型流式输出
+apollo --no-color              # 关闭 ANSI 颜色
+apollo -c                      # 继续当前项目最近会话
+apollo -r                      # 方向键选择历史会话
+apollo -r <session-id>         # 恢复指定会话
+apollo --config <path>         # 使用显式 Agent 配置
+apollo --env-file <path>       # 使用显式环境文件
+```
+
+## 配置文件
+
+配置合并顺序：内置默认值 → `~/.apollo/config.json` → 项目 `.apollo/config.json` → `--config` 指定文件。后层只覆盖它提供的字段；可选字符串的空值视为“未设置”，不会清掉上层有效提示词。
+
+常用配置：
+
+```json
+{
+  "workspaceRoot": ".",
+  "systemPrompt": "始终使用中文回答。",
+  "modeInstructions": "",
+  "maxTurns": 40,
+  "context": {
+    "maxChars": 262144,
+    "summaryChars": 12000
+  },
+  "permissions": {
+    "mode": "ask",
+    "autoApproveReadOnly": true
+  },
+  "skills": {
+    "directories": ["./skills"]
+  },
+  "mcpServers": {}
+}
+```
+
+权限模式：
+
+- `ask`：低风险读取可自动批准，写入、shell、git、外部操作等按风险询问
+- `readonly`：只允许低风险只读操作；`--yolo` 不能绕过
+- `unrestricted`：运行时自动批准，进程仍受操作系统权限约束
+
+完整字段和子 Agent 配置见自动生成的 `~/.apollo/config.example.json`。
+
+## 系统提示词与 APOLLO.md
+
+`systemPrompt` 会放在完整系统提示词最前面，之后依次拼接 Apollo 内置身份与安全规则、任务规则、工具规则、skills 规则、表达规则、项目指令、模式指令、子 Agent 规则和运行环境。
+
+Apollo 还会加载：
+
+1. 用户级 `~/.apollo/APOLLO.md` 或 `~/.apollo/apollo.md`
+2. 项目中第一个存在的 `APOLLO.md`、`apollo.md`、`AGENTS.md`、`.apollo/instructions.md`
+
+配置、系统提示词、项目指令和工具定义在一个 Engine 的对话期间冻结。修改后需要重启 Apollo 或创建新的 SDK Engine 才会生效。这也能保持厂商 Prompt Cache 的前缀稳定。
+
+## 对话与终端交互
+
+- 短的多行输入会让输入框随内容增高。
+- 大段粘贴会折叠为 `[Pasted text #N +X lines]`，提交给模型时仍恢复完整内容。
+- Agent 工作期间输入并按 Enter，会把消息加入 FIFO 队列。
+- 工作期间按 Esc 或 Ctrl-C 可中断当前回合并恢复输入框。
+- 成功的文件修改会显示 `Update(path)`、增删统计和彩色 diff。
+- `/verbose on` 可查看更完整的工具准备、执行和结果信息。
+
+## Slash 命令
+
+| 命令 | 作用 |
+|---|---|
+| `/help` | 显示命令列表 |
+| `/status` | 模型、上下文、Token、Prompt Cache 和会话状态 |
+| `/skill` | 列出内置及工作区 skills |
+| `/skill install <path> [name]` | 从本地目录或 `SKILL.md` 安装到工作区 |
+| `/simplify [focus]` | 简化并审查当前修改 |
+| `/verify [claim]` | 用可执行证据验证修改 |
+| `/debug [problem]` | 系统化复现和定位故障 |
+| `/agents` | 查看当前会话的子 Agent 活动 |
+| `/compact` | 立即语义压缩较早上下文 |
+| `/save` | 保存当前会话 |
+| `/sessions` | 列出项目会话 |
+| `/resume [session-id]` | 选择或恢复会话并显示历史记录 |
+| `/clear` | 清空当前对话上下文 |
+| `/plan` | 进入只读计划模式 |
+| `/approve` / `/reject` | 批准或拒绝 `.apollo/plan.md` |
+| `/goal <goal>` | 持续执行目标，支持 `max=N` |
+| `/goal-stop` | 停止 Goal 模式 |
+| `/workflow <goal>` | 启动研究→实现→验证→交付工作流 |
+| `/wf` | 查看工作流状态 |
+| `/memory [query]` | 列出或搜索项目记忆 |
+| `/skillify <name> \| <description>` | 从当前会话生成工作区 skill |
+| `/thought` | 展开或折叠 Thought 显示 |
+| `/verbose on\|off` | 切换详细工具过程 |
+| `/stream on\|off` | 切换流式回答 |
+| `/exit` | 保存并退出 |
+
+## 内置 skills
+
+Apollo 随 npm 包提供三个通用 skill：
+
+- `simplify`：检查复用、重复、复杂度和低效实现，只修复范围内的真实问题
+- `verify`：从需求和 diff 提取验收条件，运行真实检查并给出 PASS/FAIL/PARTIAL
+- `debug`：复现问题、验证假设、定位根因，并在要求修复时增加回归检查
+
+项目 `skills/<name>/SKILL.md` 中的同名 skill 会覆盖内置版本。用户安装的工作区 skills 不会被打进 Apollo npm 包。
+
+## 子 Agent
+
+Apollo 按需创建子 Agent，不会在启动时预先运行：
+
+- `Explore`：只读搜索、代码流追踪、完整盘点
+- `Plan`：只读分析并输出可执行计划
+- `general-purpose`：隔离执行复杂的研究、实现或混合任务
+
+主 Agent 负责用户对话和最终结论；子 Agent 没有历史对话，只接收主 Agent 写入的任务简报，且不能继续创建下级子 Agent。
+
+## 搜索、工具与 MCP
+
+内置工具包括文件读取与编辑、shell、git、Exa 搜索、网页抓取、skills、记忆、MCP、邮件、用户提问和 Task 子 Agent。
+
+- `web_search` 使用 Exa，需要 `EXA_API_KEY`，进程内对相同查询缓存 10 分钟。
+- `web_fetch` 会阻止本机、私网和危险重定向，降低 SSRF 风险。
+- `edit_file` 用于精确局部替换；`write_file` 用于新建或完整覆盖。
+- MCP 服务在 `mcpServers` 中配置，连接会在 Engine 生命周期内复用并在 `close()` 时关闭。
+
+MCP 示例：
+
+```json
+{
+  "mcpServers": {
+    "example": {
+      "command": "npx",
+      "args": ["-y", "@example/mcp-server"],
+      "env": {},
+      "cwd": "."
+    }
+  }
+}
+```
+
+## Hooks 与安全边界
+
+复制 npm 包中的 `.apollo/hooks.example.json` 为项目 `.apollo/hooks.json`：
+
+```json
+{
+  "log": true,
+  "denyTools": ["email_send"],
+  "denyMessage": "Email blocked by project hooks."
+}
+```
+
+配置文件支持在 `PreToolUse` 阶段拒绝指定工具，并选择性记录经过脱敏的 `PreToolUse`/`PostToolUse` 日志。格式错误的 hooks 配置会 fail closed，阻止工具执行。
+
+Apollo 的权限机制是应用层防线，不是操作系统沙箱。开启 `--yolo`、`unrestricted`、shell 或第三方 MCP 时，工具仍拥有当前系统用户的权限。对不可信用户或多租户服务，应在 Apollo 外使用容器或独立进程隔离。
+
+## 会话、记忆和上下文
+
+- 会话：`.apollo/sessions/`
+- 记忆：`.apollo/memory/`
+- 计划：`.apollo/plan.md`
+- hooks 日志：`.apollo/hooks.log`
+
+会话在每回合后自动保存。恢复会话时会重新显示用户和助手历史；工具内部消息和压缩摘要不会直接展示。会话文件未加密，不应包含秘密。
+
+活动上下文达到 `context.maxChars` 的 70% 时会触发语义压缩，较早原文归档在会话文件中。默认字符预算为 262144，`summaryChars` 控制摘要长度。
+
+## Prompt Cache 指标
+
+Apollo 不伪造本地 Prompt Cache 命中；`/status` 只使用模型厂商响应中的 usage 字段统计：
+
+- `hit/latest`：最近一次主模型请求的缓存命中率
+- `hit/session`：整个会话累计命中率
+- `hit/main`、`hit/task`、`hit/compaction`：按请求类别统计
+- `cache key`：稳定前缀、配置、系统提示词和工具定义的短指纹，用于诊断变化，不包含提示词正文或密钥
+
+为了提高命中率，Apollo 将稳定的 system、tools 和配置放在前面并在 Engine 生命周期内冻结；动态消息、记忆、Goal/Workflow 状态放在后面。
+
+## SDK
+
+需要嵌入 Node.js / TypeScript 服务时，请阅读 [SDK 接入指南](sdk.md)。
+
+## 故障排查
+
+- `Missing ANTHROPIC_AUTH_TOKEN`：编辑 `~/.apollo/.env` 后重启。
+- `EEXIST .../bin/apollo`：先确认 `which apollo`；移除旧的手动软链接或旧全局包后重装。
+- 搜索不可用：检查 `EXA_API_KEY`，普通文件和代码搜索不依赖 Exa。
+- 修改配置没有生效：重启 Apollo；配置和提示词在当前 Engine 中冻结。
+- 大文件工具 JSON 被截断：检查 `/status` 的 `output max`，并确认没有显式配置过低的 `ANTHROPIC_MAX_TOKENS`。