@wwkit/freetoken 1.0.1

package/client/src/data/docs/builtin-tools.js

@@ -0,0 +1,322 @@
+// opencode 内置工具的完整真实描述（直接取自 opencode 系统提示词）
+// 这些 description 是模型选择工具和构造参数的核心依据
+
+export const builtinTools = [
+  {
+    name: 'bash',
+    summary: '终端命令执行',
+    description: `Executes a given bash command in a persistent shell session with optional timeout, ensuring proper handling and security measures.
+
+Be aware: OS: linux, Shell: bash
+
+All commands run in the current working directory by default. Use the \`workdir\` parameter if you need to run a command in a different directory. AVOID using \`cd <directory> && <command>\` patterns - use \`workdir\` instead.
+
+Use \`/tmp/opencode\` for temporary work outside the workspace. This directory has already been created, already exists, and is pre-approved for external directory access.
+
+IMPORTANT: This tool is for terminal operations like git, npm, docker, etc. DO NOT use it for file operations (reading, writing, editing, searching, finding files) - use the specialized tools for this instead:
+  - File search: Use Glob (NOT find or ls)
+  - Content search: Use Grep (NOT grep or rg)
+  - Read files: Use Read (NOT cat/head/tail)
+  - Edit files: Use Edit (NOT sed/awk)
+  - Write files: Use Write (NOT echo >/cat <<EOF)
+  - Communication: Output text directly (NOT echo/printf)
+
+When issuing multiple commands:
+  - If the commands are independent and can run in parallel, make multiple bash tool calls in a single message. For example, if you need to run "git status" and "git diff", send a single message with two bash tool calls in parallel.
+  - If the commands depend on each other and must run sequentially, use a single Bash call with '&&' to chain them together (e.g., \`git add . && git commit -m "message" && git push\`). For instance, if one operation must complete before another starts (like mkdir before cp, Write before Bash for git operations, or git add before git commit), run these operations sequentially instead.
+  - Use ';' only when you need to run commands sequentially but don't care if earlier commands fail
+  - DO NOT use newlines to separate commands (newlines are ok in quoted strings)
+  - AVOID using \`cd <directory> && <command>\`. Use the \`workdir\` parameter to change directories instead.
+
+# Git and GitHub
+- Only commit, amend, push, or create PRs when explicitly requested.
+- Before committing, inspect \`git status\`, \`git diff\`, and \`git log --oneline -10\`; stage only intended files and never commit secrets.
+- Write a concise commit message that matches the repo style.
+- Do not update git config, skip hooks, use interactive \`-i\`, force-push, or create empty commits unless explicitly requested.
+- If a commit fails or hooks reject it, fix the issue and create a new commit; do not amend the failed commit.
+- Before creating a PR, inspect status, diff, remote tracking, recent commits, and the diff from the base branch.
+- Review all commits included in the PR, not just the latest commit.
+- Use \`gh\` for GitHub tasks, including PRs, issues, checks, and releases; return the PR URL when done.`,
+    parameters: {
+      type: 'object',
+      properties: {
+        command: { type: 'string', description: 'The command to execute' },
+        workdir: { type: 'string', description: 'The working directory to run the command in. Defaults to the current directory. Use this instead of `cd <directory> && <command>` patterns.' },
+        timeout: { type: 'integer', description: 'Optional timeout in milliseconds. If not specified, commands will time out after 120000ms.' },
+      },
+      required: ['command'],
+    },
+  },
+
+  {
+    name: 'read',
+    summary: '读取文件或目录',
+    description: `Read a file or directory from the local filesystem. If the path does not exist, an error is returned.
+
+Usage:
+- The \`filePath\` parameter should be an absolute path.
+- By default, this tool returns up to 2000 lines from the start of the file.
+- The \`offset\` parameter is the line number to start reading from (1-indexed).
+- To read later sections, call this tool again with a larger offset.
+- Use the grep tool to find specific content in large files or files with long lines.
+- If you are unsure of the correct file path, use the glob tool to look up filenames by glob pattern.
+- Contents are returned with each line prefixed by its line number as \`<line>: <content>\`. For example, if a file has contents "foo\\n", you will receive "1: foo\\n". For directories, entries are returned one per line (without line numbers) with a trailing \`/\` for subdirectories.
+- Any line longer than 2000 characters is truncated.
+- Call this tool in parallel when you know there are multiple files you want to read.
+- Avoid tiny repeated slices (30 line chunks). If you need more context, read a larger window.
+- This tool can read image files and PDFs and return them as file attachments.`,
+    parameters: {
+      type: 'object',
+      properties: {
+        filePath: { type: 'string', description: 'The absolute path to the file to read' },
+        offset: { type: 'integer', description: 'The line number to start reading from (1-indexed). To read later sections, call this tool again with a larger offset.' },
+        limit: { type: 'integer', description: 'The maximum number of lines to read (defaults to 2000)' },
+      },
+      required: ['filePath'],
+    },
+  },
+
+  {
+    name: 'write',
+    summary: '写入文件',
+    description: `Writes a file to the local filesystem.
+
+Usage:
+- This tool will overwrite the existing file if there is one at the provided path.
+- If this is an existing file, you MUST use the Read tool first to read the file's contents. This tool will fail if you did not read the file first.
+- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
+- NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.
+- Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked.`,
+    parameters: {
+      type: 'object',
+      properties: {
+        filePath: { type: 'string', description: 'The absolute path to the file to write (must be absolute, not relative)' },
+        content: { type: 'string', description: 'The content to write to the file' },
+      },
+      required: ['filePath', 'content'],
+    },
+  },
+
+  {
+    name: 'edit',
+    summary: '精确字符串替换编辑',
+    description: `Performs exact string replacements in files.
+
+Usage:
+- You must use your \`Read\` tool at least once in the conversation before editing. This tool will error if you attempt an edit without reading the file.
+- When editing text from Read tool output, ensure you preserve the exact indentation (tabs/spaces) as it appears AFTER the line number prefix. The line number prefix format is: line number + colon + space (e.g., \`1: \`). Everything after that space is the actual file content to match. Never include any part of the line number prefix in the oldString or newString.
+- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
+- Only use emojis if the user explicitly requests it. Avoid adding emojis to files unless asked.
+- The edit will FAIL if \`oldString\` is not found in the file with an error "oldString not found in content".
+- The edit will FAIL if \`oldString\` is found multiple times in the file with an error "Found multiple matches for oldString. Provide more surrounding lines in oldString to identify the correct match." Either provide a larger string with more surrounding context to make it unique or use \`replaceAll\` to change every instance of oldString.
+- Use \`replaceAll\` for replacing and renaming strings across the file. This parameter is useful if you want to rename a variable for instance.`,
+    parameters: {
+      type: 'object',
+      properties: {
+        filePath: { type: 'string', description: 'The absolute path to the file to modify' },
+        oldString: { type: 'string', description: 'The text to replace (must be different from newString)' },
+        newString: { type: 'string', description: 'The text to replace it with (must be different from oldString)' },
+        replaceAll: { type: 'boolean', description: 'Replace all occurrences of oldString (default false)' },
+      },
+      required: ['filePath', 'oldString', 'newString'],
+    },
+  },
+
+  {
+    name: 'glob',
+    summary: '文件名模式匹配',
+    description: `- Fast file pattern matching tool that works with any codebase size
+- Supports glob patterns like "**/*.js" or "src/**/*.ts"
+- Returns matching file paths
+- Use this tool when you need to find files by name patterns
+- When you are doing an open-ended search that may require multiple rounds of globbing and grepping, use the Task tool instead
+- You have the capability to call multiple tools in a single response. It is always better to speculatively perform multiple searches as a batch that are potentially useful.`,
+    parameters: {
+      type: 'object',
+      properties: {
+        pattern: { type: 'string', description: 'The glob pattern to match files against' },
+        path: { type: 'string', description: 'The directory to search in. If not specified, the current working directory will be used. IMPORTANT: Omit this field to use the default behavior. DO NOT enter "undefined" or "null" - simply omit it for the default behavior. Must be a valid directory path if provided.' },
+      },
+      required: ['pattern'],
+    },
+  },
+
+  {
+    name: 'grep',
+    summary: '文件内容正则搜索',
+    description: `- Fast content search tool that works with any codebase size
+- Searches file contents using regular expressions
+- Supports full regex syntax (eg. "log.*Error", "function\\s+\\w+", etc.)
+- Filter files by pattern with the include parameter (eg. "*.js", "*.{ts,tsx}")
+- Returns file paths and line numbers with matching lines
+- Use this tool when you need to find files containing specific patterns
+- If you need to identify/count the number of matches within files, use the Bash tool with \`rg\` (ripgrep) directly. Do NOT use \`grep\`
+- When you are doing an open-ended search that may require multiple rounds of globbing and grepping, use the Task tool instead`,
+    parameters: {
+      type: 'object',
+      properties: {
+        pattern: { type: 'string', description: 'The regex pattern to search for in file contents' },
+        path: { type: 'string', description: 'The directory to search in. Defaults to the current directory.' },
+        include: { type: 'string', description: 'File pattern to include in the search (e.g., "*.js", "*.{ts,tsx}")' },
+      },
+      required: ['pattern'],
+    },
+  },
+
+  {
+    name: 'lsp',
+    summary: '语言服务器协议交互',
+    description: `Interact with Language Server Protocol (LSP) servers to get code intelligence features.
+
+Supported operations:
+- goToDefinition: Find where a symbol is defined
+- findReferences: Find all references to a symbol
+- hover: Get hover information (documentation, type info) for a symbol
+- documentSymbol: Get all symbols (functions, classes, variables) in a document
+- workspaceSymbol: List project-wide symbols matching a query string
+- goToImplementation: Find implementations of an interface or abstract method
+- prepareCallHierarchy: Get call hierarchy item at a position (functions/methods)
+- incomingCalls: Find all functions/methods that call the function at a position
+- outgoingCalls: Find all functions/methods called by the function at a position
+
+All operations require:
+- filePath: The file to operate on
+- line: The line number (1-based, as shown in editors)
+- character: The character offset (1-based, as shown in editors)
+
+workspaceSymbol also accepts:
+- query: A query string to filter symbols by. Empty string requests all symbols.
+
+For workspaceSymbol, filePath is not sent in the LSP workspace/symbol request. It is used by opencode to select and start the matching LSP server.
+
+Note: LSP servers must be configured for the file type. If no server is available, an error will be returned.`,
+    parameters: {
+      type: 'object',
+      properties: {
+        operation: { type: 'string', description: 'The LSP operation to perform', enum: ['goToDefinition', 'findReferences', 'hover', 'documentSymbol', 'workspaceSymbol', 'goToImplementation', 'prepareCallHierarchy', 'incomingCalls', 'outgoingCalls'] },
+        filePath: { type: 'string', description: 'The absolute or relative path to the file' },
+        line: { type: 'integer', description: 'The line number (1-based, as shown in editors)' },
+        character: { type: 'integer', description: 'The character offset (1-based, as shown in editors)' },
+        query: { type: 'string', description: 'Search query for workspaceSymbol. Empty string requests all symbols.' },
+      },
+      required: ['operation', 'filePath', 'line', 'character'],
+    },
+  },
+
+  {
+    name: 'todowrite',
+    summary: '任务清单管理',
+    description: `Create and maintain a structured task list for the current coding session. Tracks progress, organizes multi-step work, and surfaces status to the user.
+
+## When to use
+Use proactively when:
+- The task requires 3+ distinct steps or actions (not just 3 tool calls for a single conceptual step)
+- The work is non-trivial and benefits from planning
+- The user provides multiple tasks (numbered or comma-separated) or explicitly asks for a todo list
+- New instructions arrive - capture them as todos
+- You start a task - mark it \`in_progress\` (only one at a time) before working
+- You finish a task - mark it \`completed\` and add any follow-ups discovered during the work
+
+## When NOT to use
+Skip when:
+- The work is a single, straightforward task (or <3 trivial steps)
+- The request is purely informational or conversational
+- Tracking adds no organizational value
+
+## States
+- \`pending\` - not started
+- \`in_progress\` - actively working (exactly ONE at a time)
+- \`completed\` - finished successfully
+- \`cancelled\` - no longer needed
+
+## Rules
+- Update status in real time; don't batch completions
+- Mark \`completed\` only after the required work is actually done, including any required verification. Never based on intent.
+- Keep exactly one \`in_progress\` while work remains
+- If blocked or partial, keep it \`in_progress\` and add a follow-up todo describing the blocker
+- Preserve user-provided commands verbatim (flags, args, order)
+- Items should be specific and actionable; break large work into smaller steps`,
+    parameters: {
+      type: 'object',
+      properties: {
+        todos: {
+          type: 'array',
+          description: 'The updated todo list',
+          items: {
+            type: 'object',
+            properties: {
+              content: { type: 'string', description: 'Brief description of the task' },
+              status: { type: 'string', enum: ['pending', 'in_progress', 'completed', 'cancelled'], description: 'Current status of the task' },
+              priority: { type: 'string', enum: ['high', 'medium', 'low'], description: 'Priority level of the task' },
+            },
+            required: ['content', 'status', 'priority'],
+          },
+        },
+      },
+      required: ['todos'],
+    },
+  },
+
+  {
+    name: 'task',
+    summary: '启动子 Agent',
+    description: `Launch a new agent to handle complex, multistep tasks autonomously.
+
+When using the Task tool, you must specify a subagent_type parameter to select which agent type to use.
+
+When NOT to use the Task tool:
+- If you want to read a specific file path, use the Read or Glob tool instead of the Task tool, to find the match more quickly
+- If you are searching for a specific class definition like "class Foo", use the Grep tool instead, to find the match more quickly
+- If you are searching for code within a specific file or set of 2-3 files, use the Read tool instead of the Task tool, to find the match more quickly
+- If no available agent is a good fit for the task, use other tools directly
+
+Usage notes:
+1. Launch multiple agents concurrently whenever possible, to maximize performance; to do that, use a single message with multiple tool uses
+2. Once you have delegated work to an agent, do not duplicate that work yourself. Continue with non-overlapping tasks, or wait for the result.
+3. When the agent is done, it will return a single message back to you. The result returned by the agent is not visible to the user. To show the user the result, you should send a text message back to the user with a concise summary of the result.
+4. Each agent invocation starts with a fresh context unless you provide task_id to resume the same subagent session.
+5. The agent's outputs should generally be trusted
+6. Clearly tell the agent whether you expect it to write code or just to do research (search, file reads, web fetches, etc.), since it is not aware of the user's intent. Tell it how to verify its work if possible.`,
+    parameters: {
+      type: 'object',
+      properties: {
+        description: { type: 'string', description: 'A short (3-5 words) description of the task' },
+        prompt: { type: 'string', description: 'The task for the agent to perform' },
+        subagent_type: { type: 'string', description: 'The type of specialized agent to use for this task' },
+        task_id: { type: 'string', description: 'This should only be set if you mean to resume a previous task' },
+        command: { type: 'string', description: 'The command that triggered this task' },
+      },
+      required: ['description', 'prompt', 'subagent_type'],
+    },
+  },
+
+  {
+    name: 'webfetch',
+    summary: '网页内容抓取',
+    description: `Fetches content from a specified URL
+
+- Takes a URL and optional format as input
+- Fetches the URL content, converts to requested format (markdown by default)
+- Returns the content in the specified format
+- Use this tool when you need to retrieve and analyze web content
+
+Usage notes:
+  - IMPORTANT: if another tool is present that offers better web fetching capabilities, is more targeted to the task, or has fewer restrictions, prefer using that tool instead of this one.
+  - The URL must be a fully-formed valid URL
+  - HTTP URLs will be automatically upgraded to HTTPS
+  - Format options: "markdown" (default), "text", or "html"
+  - This tool is read-only and does not modify any files
+  - Results may be summarized if the content is very large`,
+    parameters: {
+      type: 'object',
+      properties: {
+        url: { type: 'string', description: 'The URL to fetch content from' },
+        format: { type: 'string', enum: ['text', 'markdown', 'html'], description: 'The format to return the content in (defaults to markdown)' },
+        timeout: { type: 'number', description: 'Optional timeout in seconds (max 120)' },
+      },
+      required: ['url'],
+    },
+  },
+]
+
+export default builtinTools

package/client/src/data/docs/chat.js

@@ -0,0 +1,181 @@
+// Chat 子模块：LLM Chat Completions 接口详解
+export default {
+  id: 'chat',
+  name: 'Chat',
+  badge: 'LLM 接口',
+  tagline: '大语言模型 Chat Completions 接口详解',
+  description:
+    'OpenAI 兼容的 Chat Completions 接口是大语言模型最核心的 API。本节展示非流式和流式两种调用方式的完整请求与响应格式，以及核心参数说明。',
+
+  sections: [
+    // ── 非流式 ──
+    {
+      id: 'non-streaming',
+      title: '非流式请求',
+      description:
+        '一次性发送完整请求，等待模型生成完毕后返回完整响应。适合后台批处理、不需要实时展示生成过程的场景。',
+      request: `POST /v1/chat/completions
+Content-Type: application/json
+Authorization: Bearer sk-xxx
+
+{
+  "model": "maas-glm-5.1-zhipu",
+  "messages": [
+    {
+      "role": "system",
+      "content": "你是一个专业的编程助手。"
+    },
+    {
+      "role": "user",
+      "content": "用 JavaScript 写一个冒泡排序函数。"
+    }
+  ],
+  "temperature": 0.7,
+  "max_tokens": 1024
+}`,
+      response: `{
+  "id": "chatcmpl-9b8c2a3f4e5d6a7b8c9d0e1f2",
+  "object": "chat.completion",
+  "created": 1716900000,
+  "model": "maas-glm-5.1-zhipu",
+  "choices": [
+    {
+      "index": 0,
+      "message": {
+        "role": "assistant",
+        "content": "function bubbleSort(arr) {\\n  const n = arr.length;\\n  for (let i = 0; i < n - 1; i++) {\\n    for (let j = 0; j < n - 1 - i; j++) {\\n      if (arr[j] > arr[j + 1]) {\\n        [arr[j], arr[j + 1]] = [arr[j + 1], arr[j]];\\n      }\\n    }\\n  }\\n  return arr;\\n}"
+      },
+      "finish_reason": "stop"
+    }
+  ],
+  "usage": {
+    "prompt_tokens": 28,
+    "completion_tokens": 112,
+    "total_tokens": 140
+  }
+}`,
+      notes: [
+        '响应是完整的 JSON 对象，choices[0].message.content 包含完整生成内容',
+        'finish_reason 为 "stop" 表示模型自然结束，"length" 表示达到 max_tokens 截断',
+        'usage 字段包含本次调用的 token 统计，用于成本核算',
+      ],
+    },
+
+    // ── 流式 ──
+    {
+      id: 'streaming',
+      title: '流式请求',
+      description:
+        '设置 stream: true 后，服务器以 Server-Sent Events (SSE) 方式逐块返回内容。前端可实时渲染打字机效果，大幅提升用户体验。',
+      request: `POST /v1/chat/completions
+Content-Type: application/json
+Authorization: Bearer sk-xxx
+
+{
+  "model": "maas-glm-5.1-zhipu",
+  "messages": [
+    {
+      "role": "system",
+      "content": "你是一个专业的编程助手。"
+    },
+    {
+      "role": "user",
+      "content": "用 JavaScript 写一个冒泡排序函数。"
+    }
+  ],
+  "temperature": 0.7,
+  "max_tokens": 1024,
+  "stream": true
+}`,
+      response: `data: {"id":"chatcmpl-9b8c2a3f","object":"chat.completion.chunk","created":1716900000,"model":"maas-glm-5.1-zhipu","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}
+
+data: {"id":"chatcmpl-9b8c2a3f","object":"chat.completion.chunk","created":1716900000,"model":"maas-glm-5.1-zhipu","choices":[{"index":0,"delta":{"content":"function"},"finish_reason":null}]}
+
+data: {"id":"chatcmpl-9b8c2a3f","object":"chat.completion.chunk","created":1716900000,"model":"maas-glm-5.1-zhipu","choices":[{"index":0,"delta":{"content":" bubbleSort"},"finish_reason":null}]}
+
+data: {"id":"chatcmpl-9b8c2a3f","object":"chat.completion.chunk","created":1716900000,"model":"maas-glm-5.1-zhipu","choices":[{"index":0,"delta":{"content":"(arr) {\\n"},"finish_reason":null}]}
+
+data: {"id":"chatcmpl-9b8c2a3f","object":"chat.completion.chunk","created":1716900000,"model":"maas-glm-5.1-zhipu","choices":[{"index":0,"delta":{"content":"  const n = arr.length;\\n"},"finish_reason":null}]}
+
+data: {"id":"chatcmpl-9b8c2a3f","object":"chat.completion.chunk","created":1716900000,"model":"maas-glm-5.1-zhipu","choices":[{"index":0,"delta":{"content":"  // ... 后续内容逐块返回"},"finish_reason":null}]}
+
+data: {"id":"chatcmpl-9b8c2a3f","object":"chat.completion.chunk","created":1716900000,"model":"maas-glm-5.1-zhipu","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
+
+data: {"id":"chatcmpl-9b8c2a3f","object":"chat.completion.chunk","created":1716900000,"model":"maas-glm-5.1-zhipu","choices":[],"usage":{"prompt_tokens":28,"completion_tokens":112,"total_tokens":140}}
+
+data: [DONE]`,
+      notes: [
+        '每个 chunk 的 choices[0].delta.content 是增量文本片段，需在前端拼接',
+        '首个 chunk 的 delta 含 role 字段，后续 chunk 只有 content',
+        'finish_reason 出现在最后一个有内容的 chunk 上，值为 "stop"',
+        '最后一行 data: [DONE] 标记流结束，客户端应关闭连接',
+        'stream 模式下 usage 通常在最后一个 chunk（choices 为空数组时）返回',
+      ],
+    },
+
+    // ── 核心参数 ──
+    {
+      id: 'parameters',
+      title: '核心参数',
+      description: 'Chat Completions 接口的关键请求参数说明。',
+      params: [
+        {
+          name: 'model',
+          type: 'string',
+          required: true,
+          description: '模型 ID，如 maas-glm-5.1-zhipu、gpt-4o、claude-3-sonnet',
+        },
+        {
+          name: 'messages',
+          type: 'array',
+          required: true,
+          description:
+            '对话消息数组，每个元素含 role（system/user/assistant/tool）和 content',
+        },
+        {
+          name: 'temperature',
+          type: 'number',
+          required: false,
+          description: '采样温度 0~2，值越高输出越随机多样，0 最确定。默认 1',
+        },
+        {
+          name: 'max_tokens',
+          type: 'integer',
+          required: false,
+          description: '生成最大 token 数，控制响应长度上限。默认模型上限',
+        },
+        {
+          name: 'stream',
+          type: 'boolean',
+          required: false,
+          description: '是否流式返回。true 时以 SSE 逐块返回，false 一次性返回。默认 false',
+        },
+        {
+          name: 'tools',
+          type: 'array',
+          required: false,
+          description: '工具定义数组，启用 Function Calling / Agent 模式。详见 Agent 子模块',
+        },
+        {
+          name: 'tool_choice',
+          type: 'string',
+          required: false,
+          description:
+            '工具选择策略："auto"（模型自主决定）、"none"（不调用）、"required"（必须调用）、指定工具名',
+        },
+        {
+          name: 'top_p',
+          type: 'number',
+          required: false,
+          description: '核采样概率 0~1，只从累积概率达 top_p 的 token 中采样。默认 1',
+        },
+        {
+          name: 'stop',
+          type: 'string/array',
+          required: false,
+          description: '停止序列，生成中出现这些字符串时立即停止',
+        },
+      ],
+    },
+  ],
+}

package/client/src/data/docs/index.js

@@ -0,0 +1,9 @@
+import chat from './chat.js'
+import agent from './agent.js'
+import specConversion from './spec-conversion.js'
+import auth from './auth.js'
+import skills from './skills.js'
+
+export const docsModules = [chat, agent, specConversion, auth, skills]
+
+export default docsModules