@doubao-apps/ai 0.0.33 → 0.0.34

package/README.md

@@ -1,6 +1,6 @@
 # @doubao-apps/ai
 
-Doubao Apps SDK AI 工具，为 AI coding agents 提供 AI 上下文安装与 skills 管理。
+Doubao Apps SDK AI 工具，为 AI coding agents 提供 skills 管理。
 
 ## 安装
 
@@ -10,37 +10,6 @@ npm install -g @doubao-apps/ai
 
 ## 使用
 
-### 安装知识库
-
-```bash
-doubao-cli add context
-```
-
-Claude 用户可额外生成 `CLAUDE.md`：
-
-```bash
-doubao-cli add context --agent claude
-```
-
-安装后的目录结构：
-
-```text
-your-project/
-├── AGENTS.md          # AI Agent 主入口文档
-├── CLAUDE.md          # Claude 专用入口（--agent claude 时生成）
-└── references/        # 详细文档目录
-    ├── guides/        # 开发指南
-    ├── rules/         # 开发规则
-    ├── examples/      # 代码示例
-    └── reference/     # API 参考
-```
-
-### 更新知识库
-
-```bash
-doubao-cli update context
-```
-
 ### 安装 Skill
 
 ```bash

package/dist/733.js

@@ -1,30 +1,22 @@
-import l,{createRequire as e}from"node:module";let o=l.createRequire(import.meta.url);import{__webpack_require__ as t}from"./rslib-runtime.js";import{fileURLToPath as s}from"node:url";import{dirname as a}from"node:path";let i=e(import.meta.url);t.add({"node:fs"(l){l.exports=i("node:fs")},"node:path"(l){l.exports=i("node:path")},"../../ai/dist/cli.js"(l,e,t){var i=a(s(import.meta.url));let n=t("node:fs"),r=t("node:path"),c={amp:{projectPath:".agents/skills/",globalPath:"~/.config/agents/skills/"},"kimi-cli":{projectPath:".agents/skills/",globalPath:"~/.config/agents/skills/"},replit:{projectPath:".agents/skills/",globalPath:"~/.config/agents/skills/"},universal:{projectPath:".agents/skills/",globalPath:"~/.config/agents/skills/"},antigravity:{projectPath:".agent/skills/",globalPath:"~/.gemini/antigravity/skills/"},augment:{projectPath:".augment/skills/",globalPath:"~/.augment/skills/"},claude:{projectPath:".claude/skills/",globalPath:"~/.claude/skills/"},"claude-code":{projectPath:".claude/skills/",globalPath:"~/.claude/skills/"},openclaw:{projectPath:"skills/",globalPath:"~/.openclaw/skills/"},cline:{projectPath:".agents/skills/",globalPath:"~/.agents/skills/"},codebuddy:{projectPath:".codebuddy/skills/",globalPath:"~/.codebuddy/skills/"},codex:{projectPath:".agents/skills/",globalPath:"~/.codex/skills/"},"command-code":{projectPath:".commandcode/skills/",globalPath:"~/.commandcode/skills/"},continue:{projectPath:".continue/skills/",globalPath:"~/.continue/skills/"},cortex:{projectPath:".cortex/skills/",globalPath:"~/.snowflake/cortex/skills/"},crush:{projectPath:".crush/skills/",globalPath:"~/.config/crush/skills/"},cursor:{projectPath:".agents/skills/",globalPath:"~/.cursor/skills/"},droid:{projectPath:".factory/skills/",globalPath:"~/.factory/skills/"},"gemini-cli":{projectPath:".agents/skills/",globalPath:"~/.gemini/skills/"},"github-copilot":{projectPath:".agents/skills/",globalPath:"~/.copilot/skills/"},goose:{projectPath:".goose/skills/",globalPath:"~/.config/goose/skills/"},junie:{projectPath:".junie/skills/",globalPath:"~/.junie/skills/"},"iflow-cli":{projectPath:".iflow/skills/",globalPath:"~/.iflow/skills/"},kilo:{projectPath:".kilocode/skills/",globalPath:"~/.kilocode/skills/"},"kiro-cli":{projectPath:".kiro/skills/",globalPath:"~/.kiro/skills/"},kode:{projectPath:".kode/skills/",globalPath:"~/.kode/skills/"},mcpjam:{projectPath:".mcpjam/skills/",globalPath:"~/.mcpjam/skills/"},"mistral-vibe":{projectPath:".vibe/skills/",globalPath:"~/.vibe/skills/"},mux:{projectPath:".mux/skills/",globalPath:"~/.mux/skills/"},opencode:{projectPath:".agents/skills/",globalPath:"~/.config/opencode/skills/"},openhands:{projectPath:".openhands/skills/",globalPath:"~/.openhands/skills/"},pi:{projectPath:".pi/skills/",globalPath:"~/.pi/agent/skills/"},qoder:{projectPath:".qoder/skills/",globalPath:"~/.qoder/skills/"},"qwen-code":{projectPath:".qwen/skills/",globalPath:"~/.qwen/skills/"},roo:{projectPath:".roo/skills/",globalPath:"~/.roo/skills/"},trae:{projectPath:".trae/skills/",globalPath:"~/.trae/skills/"},"trae-cn":{projectPath:".trae/skills/",globalPath:"~/.trae-cn/skills/"},windsurf:{projectPath:".windsurf/skills/",globalPath:"~/.codeium/windsurf/skills/"},zencoder:{projectPath:".zencoder/skills/",globalPath:"~/.zencoder/skills/"},neovate:{projectPath:".neovate/skills/",globalPath:"~/.neovate/skills/"},pochi:{projectPath:".pochi/skills/",globalPath:"~/.pochi/skills/"},adal:{projectPath:".adal/skills/",globalPath:"~/.adal/skills/"}};function d(){try{let l=o.resolve("@byted-doubao-apps/ai-assets/manifest");return r.dirname(l)}catch{return r.join(i,"..","dist")}}function g(){return r.join(d(),"skills")}function k(l){return l.startsWith("~/")?r.join(process.env.HOME||process.env.USERPROFILE||"",l.slice(2)):l}function p(l,e){if(!n.existsSync(l))throw Error(`Source directory not found: ${l}`);for(let o of(n.mkdirSync(e,{recursive:!0}),n.readdirSync(l,{withFileTypes:!0}))){let t=r.join(l,o.name),s=r.join(e,o.name);o.isDirectory()?p(t,s):n.copyFileSync(t,s)}}function u(l){let e={agent:null,global:!1};for(let o=0;o<l.length;o++)("--agent"===l[o]||"-a"===l[o])&&l[o+1]?e.agent=l[++o]:("--global"===l[o]||"-g"===l[o])&&(e.global=!0);return e}function h(l){let e=r.join(r.join(d(),"contexts"),"doubao-apps-dev"),o=process.cwd();if(!n.existsSync(e))throw Error(`Knowledge source not found. Run build first: ${e}`);let t=r.join(e,"AGENTS.md");n.existsSync(t)&&(n.copyFileSync(t,r.join(o,"AGENTS.md")),console.log("  ✓ AGENTS.md"));let s=r.join(e,"references");if(n.existsSync(s)&&(p(s,r.join(o,"references")),console.log("  ✓ references/")),"claude"===l){let l=r.join(e,"CLAUDE.md");n.existsSync(l)&&(n.copyFileSync(l,r.join(o,"CLAUDE.md")),console.log("  ✓ CLAUDE.md"))}console.log("\nAI context installed successfully.")}function P(l,e,o){if(!c[e])throw Error(`Unknown agent: "${e}". Supported agents: ${Object.keys(c).join(", ")}`);let t=r.join(g(),l);if(!n.existsSync(t)){let e=g(),o=n.existsSync(e)?n.readdirSync(e).join(", "):"(none)";throw Error(`Skill "${l}" not found. Available skills: ${o}`)}let s=c[e],a=o?s.globalPath:s.projectPath,i=o?r.join(k(a),l):r.join(process.cwd(),a,l);for(let o of(console.log(`Installing skill "${l}" for ${e}...`),console.log(`  Target: ${i}`),n.existsSync(i)&&n.rmSync(i,{recursive:!0,force:!0}),n.mkdirSync(i,{recursive:!0}),n.readdirSync(t,{withFileTypes:!0}))){let l=r.join(t,o.name),e=r.join(i,o.name);o.isDirectory()?(p(l,e),console.log(`  ✓ ${o.name}/`)):(n.copyFileSync(l,e),console.log(`  ✓ ${o.name}`))}console.log("  ✓ Done")}l.exports={runCli:function(l={}){let e=l.commandName||"doubao-ai",[o,...t]=process.argv.slice(2);if(!o||"--help"===o||"-h"===o)return void console.log(`
+import l,{createRequire as e}from"node:module";let o=l.createRequire(import.meta.url);import{__webpack_require__ as s}from"./rslib-runtime.js";import{fileURLToPath as t}from"node:url";import{dirname as a}from"node:path";let i=e(import.meta.url);s.add({"node:fs"(l){l.exports=i("node:fs")},"node:path"(l){l.exports=i("node:path")},"../../ai/dist/cli.js"(l,e,s){var i=a(t(import.meta.url));let n=s("node:fs"),r=s("node:path"),c={amp:{projectPath:".agents/skills/",globalPath:"~/.config/agents/skills/"},"kimi-cli":{projectPath:".agents/skills/",globalPath:"~/.config/agents/skills/"},replit:{projectPath:".agents/skills/",globalPath:"~/.config/agents/skills/"},universal:{projectPath:".agents/skills/",globalPath:"~/.config/agents/skills/"},antigravity:{projectPath:".agent/skills/",globalPath:"~/.gemini/antigravity/skills/"},augment:{projectPath:".augment/skills/",globalPath:"~/.augment/skills/"},claude:{projectPath:".claude/skills/",globalPath:"~/.claude/skills/"},"claude-code":{projectPath:".claude/skills/",globalPath:"~/.claude/skills/"},openclaw:{projectPath:"skills/",globalPath:"~/.openclaw/skills/"},cline:{projectPath:".agents/skills/",globalPath:"~/.agents/skills/"},codebuddy:{projectPath:".codebuddy/skills/",globalPath:"~/.codebuddy/skills/"},codex:{projectPath:".agents/skills/",globalPath:"~/.codex/skills/"},"command-code":{projectPath:".commandcode/skills/",globalPath:"~/.commandcode/skills/"},continue:{projectPath:".continue/skills/",globalPath:"~/.continue/skills/"},cortex:{projectPath:".cortex/skills/",globalPath:"~/.snowflake/cortex/skills/"},crush:{projectPath:".crush/skills/",globalPath:"~/.config/crush/skills/"},cursor:{projectPath:".agents/skills/",globalPath:"~/.cursor/skills/"},droid:{projectPath:".factory/skills/",globalPath:"~/.factory/skills/"},"gemini-cli":{projectPath:".agents/skills/",globalPath:"~/.gemini/skills/"},"github-copilot":{projectPath:".agents/skills/",globalPath:"~/.copilot/skills/"},goose:{projectPath:".goose/skills/",globalPath:"~/.config/goose/skills/"},junie:{projectPath:".junie/skills/",globalPath:"~/.junie/skills/"},"iflow-cli":{projectPath:".iflow/skills/",globalPath:"~/.iflow/skills/"},kilo:{projectPath:".kilocode/skills/",globalPath:"~/.kilocode/skills/"},"kiro-cli":{projectPath:".kiro/skills/",globalPath:"~/.kiro/skills/"},kode:{projectPath:".kode/skills/",globalPath:"~/.kode/skills/"},mcpjam:{projectPath:".mcpjam/skills/",globalPath:"~/.mcpjam/skills/"},"mistral-vibe":{projectPath:".vibe/skills/",globalPath:"~/.vibe/skills/"},mux:{projectPath:".mux/skills/",globalPath:"~/.mux/skills/"},opencode:{projectPath:".agents/skills/",globalPath:"~/.config/opencode/skills/"},openhands:{projectPath:".openhands/skills/",globalPath:"~/.openhands/skills/"},pi:{projectPath:".pi/skills/",globalPath:"~/.pi/agent/skills/"},qoder:{projectPath:".qoder/skills/",globalPath:"~/.qoder/skills/"},"qwen-code":{projectPath:".qwen/skills/",globalPath:"~/.qwen/skills/"},roo:{projectPath:".roo/skills/",globalPath:"~/.roo/skills/"},trae:{projectPath:".trae/skills/",globalPath:"~/.trae/skills/"},"trae-cn":{projectPath:".trae/skills/",globalPath:"~/.trae-cn/skills/"},windsurf:{projectPath:".windsurf/skills/",globalPath:"~/.codeium/windsurf/skills/"},zencoder:{projectPath:".zencoder/skills/",globalPath:"~/.zencoder/skills/"},neovate:{projectPath:".neovate/skills/",globalPath:"~/.neovate/skills/"},pochi:{projectPath:".pochi/skills/",globalPath:"~/.pochi/skills/"},adal:{projectPath:".adal/skills/",globalPath:"~/.adal/skills/"}};function d(){return r.join(i,"..","dist")}function g(l={}){return r.join(function(l={}){if(l.preferBundledAssets)return d();try{let l=o.resolve("@byted-doubao-apps/ai-assets/manifest");return r.dirname(l)}catch{return d()}}(l),"skills")}function k(l){return l.startsWith("~/")?r.join(process.env.HOME||process.env.USERPROFILE||"",l.slice(2)):l}function p(l){let e={agent:null,global:!1};for(let o=0;o<l.length;o++)("--agent"===l[o]||"-a"===l[o])&&l[o+1]?e.agent=l[++o]:("--global"===l[o]||"-g"===l[o])&&(e.global=!0);return e}function h(l,e,o,s={}){if(!c[e])throw Error(`Unknown agent: "${e}". Supported agents: ${Object.keys(c).join(", ")}`);let t=function(l,e={}){return r.join(g(e),l)}(l,s);if(!n.existsSync(t)){let e=g(s),o=n.existsSync(e)?n.readdirSync(e).join(", "):"(none)";throw Error(`Skill "${l}" not found. Available skills: ${o}`)}let a=c[e],i=o?a.globalPath:a.projectPath,d=o?r.join(k(i),l):r.join(process.cwd(),i,l);for(let o of(console.log(`Installing skill "${l}" for ${e}...`),console.log(`  Target: ${d}`),n.existsSync(d)&&n.rmSync(d,{recursive:!0,force:!0}),n.mkdirSync(d,{recursive:!0}),n.readdirSync(t,{withFileTypes:!0}))){let l=r.join(t,o.name),e=r.join(d,o.name);o.isDirectory()?(!function l(e,o){if(!n.existsSync(e))throw Error(`Source directory not found: ${e}`);for(let s of(n.mkdirSync(o,{recursive:!0}),n.readdirSync(e,{withFileTypes:!0}))){let t=r.join(e,s.name),a=r.join(o,s.name);s.isDirectory()?l(t,a):n.copyFileSync(t,a)}}(l,e),console.log(`  ✓ ${o.name}/`)):(n.copyFileSync(l,e),console.log(`  ✓ ${o.name}`))}console.log("  ✓ Done")}l.exports={runCli:function(l={}){let e=l.commandName||"doubao-ai",o={preferBundledAssets:!0===l.preferBundledAssets},[s,...t]=process.argv.slice(2);if(!s||"--help"===s||"-h"===s)return void console.log(`
 ${e} - Doubao Apps SDK AI 工具
 
 用法：
-  ${e} add context [--agent <agent>]       安装 AI 上下文到当前项目
-  ${e} update context                      更新已安装的 AI 上下文
   ${e} skills add <skill1> [skill2...] --agent <agent>  安装一个或多个 skill 到指定 Agent
   ${e} skills list                         查看可用 skills
   ${e} skills update [--global]            更新所有已安装的 skills
 
 选项：
-  --agent <agent>    指定 AI Agent（如 claude、claude-code、cursor）
+  --agent <agent>    指定 AI Agent（如 claude-code、opencode、cursor）
   --global, -g       全局安装（用户目录而非项目目录）
 
 示例：
-  # 安装 AI 上下文（通用）
-  ${e} add context
-
-  # 安装 AI 上下文（Claude 专用，额外生成 CLAUDE.md）
-  ${e} add context --agent claude
-
-  # 更新已安装的 AI 上下文
-  ${e} update context
-
   # 安装一个或多个 skill 到 Claude Code
   ${e} skills add doubao-apps-dev quality-gate --agent claude-code
 
+  # 安装 skill 到 opencode
+  ${e} skills add doubao-apps-dev --agent opencode
+
   # 全局安装 skill
   ${e} skills add doubao-apps-dev --agent claude-code --global
 
@@ -36,6 +28,6 @@ ${e} - Doubao Apps SDK AI 工具
 
 支持的 Agents：
   ${Object.keys(c).join(", ")}
-`);if("add"===o){let[l,...e]=t;"context"!==l&&(console.error(`Unknown target: "${l}". Supported: context`),process.exit(1));let{agent:o}=u(e);console.log(`Installing AI context${o?` (--agent ${o})`:""}...`),h(o);return}if("update"===o){let l,o,s,[a]=t;"context"!==a&&(console.error(`Unknown target: "${a}". Supported: context`),process.exit(1)),l=process.cwd(),o=n.existsSync(r.join(l,"AGENTS.md")),s=n.existsSync(r.join(l,"CLAUDE.md")),o||s?(console.log("Updating knowledge base..."),h(s?"claude":null)):console.log(`No AI context found in current directory. Run \`${e} add context\` first.`);return}if("skills"===o){let[l,...o]=t;if("list"===l)return void function(){let l=g();if(!n.existsSync(l))return console.log("No skills available. Run build first.");let e=n.readdirSync(l,{withFileTypes:!0}).filter(l=>l.isDirectory()).map(l=>l.name);if(0===e.length)return console.log("No skills available.");for(let o of(console.log("Available skills:"),e)){let e=r.join(l,o,"SKILL.md");console.log(`  - ${o}${n.existsSync(e)?"":" (not built)"}`)}}();if("add"===l){let{agent:l,global:t}=u(o),s=[];for(let l=0;l<o.length;l++){let e=o[l];if("--agent"===e||"-a"===e)l++;else{if("--global"===e||"-g"===e)continue;s.push(e)}}for(let o of(0===s.length&&(console.error(`Usage: ${e} skills add <skill-name>... --agent <agent>`),process.exit(1)),l||(console.error(`--agent is required. Example: ${e} skills add doubao-apps-dev --agent claude-code`),process.exit(1)),s))P(o,l,t);return}if("update"===l){let{global:l}=u(o);!function(l){let e=g();if(!n.existsSync(e))return console.log("No skills to update. Run build first.");let o=n.readdirSync(e,{withFileTypes:!0}).filter(l=>l.isDirectory()).map(l=>l.name),t=0;for(let[e,s]of Object.entries(c)){let a=l?s.globalPath:s.projectPath,i=l?k(a):r.join(process.cwd(),a);for(let s of o)n.existsSync(r.join(i,s))&&(P(s,e,l),t++)}0===t?console.log("No installed skills found to update."):console.log(`
-Updated ${t} skill installation(s).`)}(l);return}console.error(`Unknown skills subcommand: "${l}". Use: add, list, update`),process.exit(1)}console.error(`Unknown command: "${o}". Run \`${e} --help\` for usage.`),process.exit(1)}}}});
+`);if("skills"===s){let[l,...s]=t;if("list"===l)return void function(l={}){let e=g(l);if(!n.existsSync(e))return console.log("No skills available. Run build first.");let o=n.readdirSync(e,{withFileTypes:!0}).filter(l=>l.isDirectory()).map(l=>l.name);if(0===o.length)return console.log("No skills available.");for(let l of(console.log("Available skills:"),o)){let o=r.join(e,l,"SKILL.md");console.log(`  - ${l}${n.existsSync(o)?"":" (not built)"}`)}}(o);if("add"===l){let{agent:l,global:t}=p(s),a=[];for(let l=0;l<s.length;l++){let e=s[l];"--agent"===e||"-a"===e?l++:"--global"!==e&&"-g"!==e&&a.push(e)}for(let s of(0===a.length&&(console.error(`Usage: ${e} skills add <skill-name>... --agent <agent>`),process.exit(1)),l||(console.error(`--agent is required. Example: ${e} skills add doubao-apps-dev --agent claude-code`),process.exit(1)),a))h(s,l,t,o);return}if("update"===l){let{global:l}=p(s);!function(l,e={}){let o=g(e);if(!n.existsSync(o))return console.log("No skills to update. Run build first.");let s=n.readdirSync(o,{withFileTypes:!0}).filter(l=>l.isDirectory()).map(l=>l.name),t=0;for(let[o,a]of Object.entries(c)){let i=l?a.globalPath:a.projectPath,c=l?k(i):r.join(process.cwd(),i);for(let a of s)n.existsSync(r.join(c,a))&&(h(a,o,l,e),t++)}0===t?console.log("No installed skills found to update."):console.log(`
+Updated ${t} skill installation(s).`)}(l,o);return}console.error(`Unknown skills subcommand: "${l}". Use: add, list, update`),process.exit(1)}console.error(`Unknown command: "${s}". Run \`${e} --help\` for usage.`),process.exit(1)}}}});
 //# sourceMappingURL=733.js.map

package/dist/cli.js

@@ -1,2 +1,2 @@
-import"node:module";import{__webpack_require__ as o}from"./rslib-runtime.js";import"./733.js";(0,o("../../ai/dist/cli.js").runCli)({commandName:"doubao-cli"});
+import"node:module";import{__webpack_require__ as o}from"./rslib-runtime.js";import"./733.js";(0,o("../../ai/dist/cli.js").runCli)({commandName:"doubao-cli",preferBundledAssets:!0});
 //# sourceMappingURL=cli.js.map

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
-  "packageName": "@byted-doubao-apps/ai-assets",
-  "version": "0.0.33",
-  "generatedAt": "2026-06-09T07:17:40.355Z",
+  "packageName": "@doubao-apps/ai",
+  "version": "0.0.34",
+  "generatedAt": "2026-06-10T12:55:28.312Z",
   "skills": [
     {
       "name": "doubao-apps-dev",
@@ -33,13 +33,5 @@
       "entry": "skills/weixin-to-doubao/SKILL.md",
       "hasAiDir": true
     }
-  ],
-  "contexts": [
-    {
-      "name": "doubao-apps-dev",
-      "entry": "contexts/doubao-apps-dev/AGENTS.md",
-      "claudeEntry": "contexts/doubao-apps-dev/CLAUDE.md",
-      "hasAiDir": true
-    }
   ]
 }

package/dist/skills/doubao-apps-dev/SKILL.md

@@ -2,14 +2,14 @@
 name: doubao-apps-dev
 description:
   Doubao Apps SDK (框架/framework) 开发指南。用于开发豆包小程序应用，
-  包含 Page（页面）、Widget（卡片）组件开发、Bridge API 系统能力调用、生命周期管理等。
+  包含 Page（页面）、Widget（卡片）组件开发、Open API / 端能力调用、生命周期管理等。
   基于 React Lynx 框架，使用 TSX/JSX 语法和 React Hooks 开发模式，并且提供了内置 UI 组件开箱即用。
   当用户开发豆包应用、创建页面或卡片组件、调用端能力 API 时使用此技能。
 ---
 
-# Doubao Apps SDK AI 开发指南
+# Doubao Apps SDK 开发指南
 
-本文件专供 AI coding agents（如 Claude、Copilot、Cursor）和开发者使用，提供 Doubao Apps SDK 框架的快速入门、开发规则和文档导航。
+本文件供开发者和 AI coding agents（如 Claude、Copilot、Cursor）使用，提供 Doubao Apps SDK 框架的快速入门、开发规则和文档导航。
 
 ---
 
@@ -17,29 +17,33 @@ description:
 
 ### 1. 项目介绍
 
-Doubao Apps SDK 是豆包应用开发框架，基于 React Lynx 框架提供完整的小程序开发、构建和部署能力。
+Doubao Apps SDK 是豆包应用开发框架，基于 React Lynx 框架提供完整的小程序开发和构建能力。
 
 **核心特性**：
 - **React 风格开发**：使用 TSX/JSX 语法和 React Hooks
 - **Lynx 渲染引擎**：跨平台高性能渲染
-- **Bridge API**：150+ 系统能力接口
-- **完整工具链**：CLI、调试工具、部署系统
+- **Open API / 端能力**：网络、存储、位置、导航、Toast 等系统能力
+- **完整工具链**：CLI、调试工具、构建能力
 
 ### 2. 环境准备
 
 **必需环境**：
 - Node.js 20+
 - pnpm（推荐）：`npm install -g pnpm`
-- bnpm 源：`npm config set registry https://bnpm.byted.org`
 
 
 ### 3. 创建项目
 
+
+**外网创建：**
+
 ```bash
-# 创建一个名为 my-doubao-app 的 empty 工程，应用 ID 为 <app-id>，路径为 <path>，务必传入当前绝对路径
-npx -y --registry=https://bnpm.byted.org @byted-doubao-tools/doubao-cli-dev dev project create --name my-doubao-app --app-id <app-id> --path <path>
+# 使用 create 创建一个名为 my-doubao-app 的 starter 工程
+npm create @doubao-apps my-doubao-app -- --template starter -y
+# 如果预期就地创建工程，使用 . 作为目录名
+# npm create @doubao-apps . -- --template starter -y
 
-# 进入项目目录
+# 进入项目目录 (如果就地创建工程，则不需要执行 cd)
 cd my-doubao-app
 
 # 安装依赖
@@ -51,9 +55,10 @@ pnpm install
 ```
 my-doubao-app/
 ├── package.json          # 依赖管理
-├── pnpm-lock.yaml        # 依赖锁定
 └── src/
     ├── app.ts            # 应用入口
+    ├── app.config.ts     # 应用配置
+    ├── mcp-ui/           # 可选登录、隐私授权和 MCP 特殊页面约定目录
     ├── pages/            # 页面目录（全屏UI）
     │   └── home/
     │       ├── index.tsx
@@ -72,267 +77,138 @@ my-doubao-app/
 
 - **优先使用 pnpm** 作为包管理器
 - **分离样式文件**：每个组件使用独立的 `.scss` 文件
-- **配置 App 元信息**：`src/app.config.ts` 需要配置 `appId` 和 `name`；`pages` / `widgets` 是可选的显式入口配置
+- **配置 App 元信息**：`src/app.config.ts` 需要配置 `appId` 和 `name`；`appId` 使用开放平台 `db_xxxxxx` 风格；`pages` / `widgets` 是可选的显式入口配置
 - **使用生命周期钩子**：合理使用 `onShow`、`onMounted` 等
-- **TypeScript 类型**：使用 `getViewData<T>()`、为 props 和 state 提供类型定义
+- **TypeScript 类型**：所有 Page / Widget 默认使用 `getViewData<T>()`，为 viewData、props 和 state 提供明确类型；不要使用裸 `getViewData()`、`getViewData<any>()`、`: any`
+- **Open API 导入**：`request`、`getLocation`、`showToast`、`navigateTo` 等端能力从 `@doubao-apps/framework/api` 导入；参数和返回值以 [Framework API 快速参考](references/reference/framework-api-quick-ref.md) / [Open API 目录](references/reference/open-api/README.md) 为准
+- **异步状态**：Open API 和异步请求必须在 `useEffect`、生命周期钩子或事件处理函数中调用，并包含 loading、error、success 状态
+- **内置组件**：`button`、`switch`、`slider` 等直接使用小写标签，不要从组件包 import；`button` 点击使用 `onClick`，不要使用 `onTap` / `bindtap`；事件和 props 先查 [组件库快速参考](references/reference/components-quick-ref.md)
+- **Framework Hooks**：`useState`、`useEffect` 等 Hooks 必须从 `@doubao-apps/framework` 导入，不要从 `react` 导入
 - **错误处理**：处理边界情况和错误状态
 
 ### 禁止做法
 
 - **不写内联样式**：避免在 TSX 中直接写 style
-- **不在 render 中请求**：异步操作应在生命周期钩子中进行
+- **不在 render 中请求**：不要在 `render()` 中直接调用 `request`、`getLocation`、`showToast`、`navigateTo`、`fetch` 等异步或系统 API
 - **不过度嵌套**：保持组件层级扁平化
 - **不忽略类型**：避免使用 `any` 类型
 
-### ⚠️ 文件命名约束
+### Page / Widget 推荐入口模板
 
-页面/卡片目录下的入口文件必须命名为 **`index.tsx`**，样式文件为 **`index.scss`**。
+开发 Page / Widget 时，先确定视图输入类型、入口组件和 `src/app.config.ts` 注册方式。需要调用端能力时，在这个入口形态上补充
+[常用开发模式](references/examples/common-patterns.md) 中的异步状态；具体端能力组合示例见
+[Open API 使用配方](references/examples/open-api-recipes.md)。
 
-**详细规则** → [references/rules/dos-and-donts.md](references/rules/dos-and-donts.md)
+```tsx
+import { defineWidget, getViewData } from '@doubao-apps/framework';
+import './index.scss';
 
----
+interface LocationCardData {
+  title?: string;
+}
 
-## 组件开发
+function LocationCard() {
+  const viewData = getViewData<LocationCardData>();
 
-### Page（页面）
+  return <view className="location-card">{viewData.title || '位置卡片'}</view>;
+}
 
-Page 是全屏 UI 组件，支持九宫格、浮窗等变体。
+export default defineWidget({
+  render() {
+    return <LocationCard />;
+  }
+});
+```
 
-**可选 pages 配置**：
 ```ts
+// src/app.config.ts：使用数组写法；entry 写到 index，不要省略入口文件名
 import { defineAppConfig } from '@doubao-apps/kit';
 
 export default defineAppConfig({
-  appId: 'com.example.my-doubao-app',
-  name: '我的豆包应用',
-  pages: [
+  appId: 'db_xxxxxx',
+  name: '位置能力示例',
+  widgets: [
     {
-      entry: 'pages/home/index',
-      id: 'my-page',
-      title: '我的页面',
-      description: '页面功能描述'
+      entry: 'widgets/location-card/index',
+      id: 'location-card',
+      name: '位置卡片',
+      description: '展示位置能力结果'
     }
   ]
 });
 ```
 
-`src/app.config.ts` 是应用配置文件，需要配置 `appId` 和 `name`。`pages` 数组是可选配置；`src/pages/home/index.tsx`
-这类一级目录即使不写进 `pages` 也会被自动发现，默认 `pageId` 是目录名 `home`，但 `title`、`description`
-等页面 metadata 为空。
-
-**什么时候需要配置**：需要设置标题/描述等 metadata、稳定首页入口、或声明多级目录时，使用 `pages` 数组。`pages`
-第一项会作为应用首页（最终 manifest 的 `appletEntry`）。如果希望 `home` 作为默认打开页面，把
-`pages/home/index` 放在第一项；多页面应用继续按顺序声明其他页面。
-
-如果只是声明入口、不补 metadata，可以直接写字符串：
-
-```ts
-export default defineAppConfig({
-  appId: 'com.example.my-doubao-app',
-  name: '我的豆包应用',
-  pages: ['pages/home/index', 'pages/account/demo/index']
-});
-```
-
-**不配置 `pages` 时**：一级页面仍会产出；如果没有显式 `pages` 顺序，首页入口会走构建兜底/历史默认 `index`。
-首页不是 `index` 时，建议显式配置 `pages` 第一项。
+端能力参数/返回值和内置组件 props 的高风险细节维护在 reference 子文档中；生成前优先查对应小节，不要在主流程里临时扩展字段。
+如果需求里混入 `fetch`、`window`、`document`、`localStorage`、`style={{}}` 等 Web/H5 写法，先按文档导航里的“Web 写法纠偏”确认替代写法，再实现。
 
-**多级目录**：`src/pages/account/demo/index.tsx` 不会被一级目录扫描自动发现，需要写
-`entry: 'pages/account/demo/index'`。如果不写 `id`，默认 `pageId` 是最后一级目录名 `demo`。
-
-**页面实现**：
-```tsx
-import { definePage, getViewData } from '@doubao-apps/framework';
-import './index.scss';
+### ⚠️ 文件命名约束
 
-interface HomePageData {
-  title: string;
-}
+页面/卡片目录下的入口文件必须命名为 **`index.tsx`**，样式文件为 **`index.scss`**。
 
-export default definePage({
-  onShow() {
-    // 页面显示时触发
-  },
-  render() {
-    const viewData = getViewData<HomePageData>();
-    return <view>{viewData.title}</view>;
-  }
-});
-```
+**详细规则** → [references/rules/dos-and-donts.md](references/rules/dos-and-donts.md)
 
-**开发指南** → [references/guides/component-development.md](references/guides/component-development.md)
+---
 
-### Widget（卡片）
+## 组件开发速记
 
-Widget 是聊天流中的卡片组件，在对话中展示。
+- **Page**：全屏 UI，放在 `src/pages/<page-name>/index.tsx` 和 `index.scss`，入口使用 `definePage`。
+- **Widget**：聊天流卡片，放在 `src/widgets/<widget-name>/index.tsx` 和 `index.scss`，入口使用 `defineWidget`。
+- **入口注册**：`src/app.config.ts` 通过 `defineAppConfig` 配置 `appId`、`name`，`appId` 使用开放平台 `db_xxxxxx` 风格，并按需声明 `pages` / `widgets`。
+- **自动发现**：一级 `src/pages/*/index.tsx`、`src/widgets/*/index.tsx` 可自动发现；需要 metadata、稳定首页顺序或多级目录时显式声明。
+- **数组写法**：只声明入口可写字符串；补 metadata 时写对象。Page 对象使用 `title`，Widget 对象使用 `name`，`entry` 写完整到 `index`。
 
-**可选 widgets 配置**：
 ```ts
 import { defineAppConfig } from '@doubao-apps/kit';
 
 export default defineAppConfig({
-  appId: 'com.example.my-doubao-app',
+  appId: 'db_xxxxxx',
   name: '我的豆包应用',
+  pages: [
+    'pages/home/index',
+    {
+      entry: 'pages/account/settings/index',
+      id: 'account-settings',
+      title: '账号设置页'
+    }
+  ],
   widgets: [
+    'widgets/order/detail/index',
     {
-      entry: 'widgets/my-widget/index',
-      id: 'my-widget',
-      name: '我的卡片',
-      description: '卡片功能描述',
-      boxType: 'inbox',
-      border: true
+      entry: 'widgets/order/summary/index',
+      id: 'order-summary',
+      name: '订单摘要卡片'
     }
   ]
 });
 ```
 
-`src/widgets/my-widget/index.tsx` 这类一级目录即使不配置也会被自动发现，默认 `widgetId` 是目录名
-`my-widget`，`name`、`description` 等 metadata 为空。多级目录如 `src/widgets/order/detail/index.tsx`
-需要在 `widgets` 数组中显式写 `entry: 'widgets/order/detail/index'`。
-
-如果只是声明入口、不补 metadata，可以直接写字符串：
-
-```ts
-export default defineAppConfig({
-  appId: 'com.example.my-doubao-app',
-  name: '我的豆包应用',
-  widgets: ['widgets/my-widget/index', 'widgets/order/detail/index']
-});
-```
-
-**卡片实现**：
-```tsx
-import { defineWidget, getViewData } from '@doubao-apps/framework';
-import './index.scss';
-
-interface MyWidgetData {
-  title: string;
-}
-
-export default defineWidget({
-  onMounted() {
-    // 卡片挂载后触发
-  },
-  render() {
-    const viewData = getViewData<MyWidgetData>();
-    return <view>{viewData.title}</view>;
-  }
-});
-```
-
-**开发指南** → [references/guides/component-development.md](references/guides/component-development.md)
-
-**基础示例对比** → [references/examples/component-basics.md](references/examples/component-basics.md)
-
----
-
-## 开发资源
-
-### 开发任务模板
-
-根据不同的开发任务，使用不同的知识文档：
-
-| 任务类型 | 文档 | 适用场景 |
-|---------|-----------|---------|
-| 组件开发 | [component-development.md](references/guides/component-development.md) | Page 和 Widget 完整开发指南 |
-| 最佳实践 | [best-practices.md](references/guides/best-practices.md) | 代码规范、架构设计 |
-| 性能优化 | [performance-optimization.md](references/guides/performance-optimization.md) | 渲染优化、内存管理 |
-| 问题排查 | [troubleshooting.md](references/guides/troubleshooting.md) | 调试技巧、常见问题 |
-
----
-
-## API 参考
-
-完整的 Framework API（框架核心）和 Bridge API（系统能力）列表：
-
-- **[Framework API 快速参考](references/reference/framework-api-quick-ref.md)** - 核心 Framework API 速查
-- **[Open API 目录](references/reference/open-api/README.md)** - 公开可用的端能力（系统能力）目录与详细文档
-- **[组件库快速参考](references/reference/components-quick-ref.md)** - SDK 内置组件（Button、Switch、Swiper 等）
-
-包含：
-- **Framework API**：组件定义（definePage、defineWidget）、生命周期、状态管理
-- **Components**：SDK 内置 UI 组件（Button、Switch、Slider、Swiper、Dialog 等）
-- **Bridge API**：系统能力接口（网络、存储、设备、UI 交互等）
-
-### Playground 测试页范式
-
-当任务涉及 `examples/playground`、Open API 测试页、JSB 验证页或组件 Demo 时，必须按当前 Playground 结构编写：
-
-- **API 测试页**：放在 `examples/playground/src/pages/api/<group>/<api-name>/index.tsx`，并同步 `src/case-metadata.ts` 与 `src/pages/api/registry.ts`；`apiCaseMetas.name` 使用 `<group>/<api-name>`，允许带 `/`。
-- **组件测试页**：放在 `examples/playground/src/pages/component/<component-name>/index.tsx`，并同步 `src/case-metadata.ts` 与 `src/pages/component/registry.ts`。
-- **页面结构**：直接写 `definePage`、`PlaygroundPage`、纵向排列的多个 `TestCase`、`ActionButton` 和真实 API/组件调用，禁止任何页面工厂函数。
-- **覆盖方式**：API 页尽可能覆盖参数组合、边界值、失败路径和事件回调；组件页覆盖默认态、边界态和交互态。不要只写 2～3 个 happy path。
-- **日志隔离**：多个 `TestCase` 不共用同一个日志 state；日志 payload 可带 `case` / `caseName`，避免不同日志面板串扰。
-- **路由编码**：入口页跳转含 `/` 的 case name 时必须 `encodeURIComponent`；开发模式 `delegate-page` 的 query 需要 encode/decode。
-- **响应式主题**：Playground 外壳和示例辅助 UI 使用 `--pg-*` 变量；不要在 Playground 任务中顺手修组件库自身主题。
-
-### Lynx 组件
-
-Lynx 组件库完整参考文档请访问官方文档：
-
-👉 **[Lynx 官方文档](https://lynx.bytedance.net/next/llms.txt)**
+详细 Page / Widget 生命周期、布局、metadata、boxType 和 viewData 示例见 [组件开发指南](references/guides/component-development.md)，基础示例对比见 [component-basics.md](references/examples/component-basics.md)。
 
 ---
 
-## 代码示例
-
-### 常用场景
-
-| 场景 | 示例文档 | 说明 |
-|-----|---------|------|
-| 组件基础 | [component-basics.md](references/examples/component-basics.md) | Page 和 Widget 基础示例对比 |
-| 常用模式 | [common-patterns.md](references/examples/common-patterns.md) | API 集成、状态管理、页面导航 |
-
----
-
-## 外部资源
-
-### 快速参考
-
-API 参考文档
-
-- **[Framework API](references/reference/framework-api-quick-ref.md)** - 核心 Framework API 速查
-- **[组件库](references/reference/components-quick-ref.md)** - SDK 内置组件速查
-- **[Open API](references/reference/open-api/README.md)** - 系统能力 API 目录与详细文档
-
-### 依赖包
-
-- **Framework**：`@doubao-apps/framework` - 核心框架
-- **端能力 API**：`@doubao-apps/framework/api` - 系统能力接口
-- **Kit**：`@doubao-apps/kit` - 开发工具包
-
----
-
-## 获取帮助
-
-### 常见问题
-
-遇到问题？先查看故障排查指南：
-
-👉 **[故障排查指南](references/guides/troubleshooting.md)**
-
-### 最佳实践
-
-想要提升代码质量？查看最佳实践：
-
-👉 **[最佳实践指南](references/guides/best-practices.md)**
-
-### 性能优化
-
-应用性能不佳？查看性能优化指南：
-
-👉 **[性能优化指南](references/guides/performance-optimization.md)**
-
----
-
-## 知识库文档组织
-
-```
-<skill-directory>/
-├── SKILL.md            # 主入口文档（AI Agent 必读）
-└── references/         # 详细文档目录
-    ├── guides/         # 开发指南
-    ├── rules/          # 开发规则
-    ├── examples/       # 代码示例
-    └── reference/      # API 参考
-```
+## 文档导航
+
+| 场景 | 文档 | 何时使用 |
+|-----|------|----------|
+| 开发规则 | [dos-and-donts.md](references/rules/dos-and-donts.md) | 需要确认禁止项、类型规则、样式规则 |
+| Page / Widget | [component-development.md](references/guides/component-development.md) | 创建页面、卡片、配置 metadata、处理生命周期 |
+| MCP UI | [mcp-ui.md](references/guides/mcp-ui.md) | 配置 `mcp-ui` 登录、隐私授权和自定义登录页 |
+| 失效卡片 | [expired-widget.md](references/guides/expired-widget.md) | 使用 `expiredWidget()` 把过期 Widget 更新为内置失效卡 |
+| Web 写法纠偏 | [dos-and-donts.md](references/rules/dos-and-donts.md)、[common-patterns.md](references/examples/common-patterns.md)、[open-api-recipes.md](references/examples/open-api-recipes.md) | 需求出现 `fetch`、`window`、`document`、`localStorage`、内联 `style` 等 Web/H5 写法时 |
+| API 集成和状态 | [common-patterns.md](references/examples/common-patterns.md) | 异步调用结构、错误处理、状态管理、导航 |
+| Open API 使用配方 | [open-api-recipes.md](references/examples/open-api-recipes.md) | 参考 `getLocation`、Storage 等端能力和 Page / Widget 的组合写法 |
+| 内置组件使用配方 | [component-recipes.md](references/examples/component-recipes.md) | 参考 `button`、`switch`、`slider` 等组件和状态的组合写法 |
+| Framework API | [framework-api-quick-ref.md](references/reference/framework-api-quick-ref.md) | 查 `definePage`、`defineWidget`、Hooks、viewData、常用端能力签名 |
+| Open API 详情 | [open-api/README.md](references/reference/open-api/README.md) | 查系统能力 API 的完整参数和返回值 |
+| 内置组件 | [components-quick-ref.md](references/reference/components-quick-ref.md) | 使用 `button`、`switch`、`slider`、`swiper` 等全局小写组件 |
+| 最佳实践 | [best-practices.md](references/guides/best-practices.md) | 代码组织、错误处理、可维护性 |
+| 性能优化 | [performance-optimization.md](references/guides/performance-optimization.md) | 渲染、列表、资源和内存优化 |
+| 问题排查 | [troubleshooting.md](references/guides/troubleshooting.md) | 编译、运行、样式、API 调用异常 |
+
+## 依赖包
+
+- **Framework**：`@doubao-apps/framework` - 核心框架、视图入口、Hooks、viewData
+- **端能力 API**：`@doubao-apps/framework/api` - 网络、存储、位置、导航、Toast 等系统能力
+- **Kit**：`@doubao-apps/kit` - `defineAppConfig` 和构建配置能力
+
+Lynx 组件库完整参考：<https://lynxjs.org/zh/>