From bbec17b439bd550497def6ef3a81fbf0e79790f1 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Sat, 18 Jul 2026 05:52:41 +0000 Subject: [PATCH] docs: translate all content to cn, ar, hi, zh, zh-Hans --- mintlify/ar/cli/config.mdx | 91 +++++ mintlify/ar/cli/core.mdx | 77 ++++ mintlify/ar/cli/memory.mdx | 107 ++++++ mintlify/ar/cli/overview.mdx | 60 +++ mintlify/ar/cli/quality.mdx | 84 ++++ mintlify/ar/cli/substrate.mdx | 103 +++++ mintlify/ar/concepts/config-compiler.mdx | 97 +++++ mintlify/ar/concepts/cross-session-memory.mdx | 86 +++++ mintlify/ar/concepts/model-routing.mdx | 78 ++++ mintlify/ar/concepts/pre-action-gate.mdx | 100 +++++ .../ar/concepts/proof-carrying-memory.mdx | 109 ++++++ mintlify/ar/concepts/verification-gates.mdx | 98 +++++ mintlify/ar/guides/radar-deps.mdx | 65 ++++ mintlify/ar/guides/team-memory.mdx | 76 ++++ mintlify/ar/guides/zero-config-onboarding.mdx | 86 +++++ mintlify/ar/installation.mdx | 106 +++++ mintlify/ar/introduction.mdx | 130 +++++++ mintlify/ar/quickstart.mdx | 107 ++++++ mintlify/cn/cli/config.mdx | 91 +++++ mintlify/cn/cli/core.mdx | 76 ++++ mintlify/cn/cli/memory.mdx | 107 ++++++ mintlify/cn/cli/overview.mdx | 61 +++ mintlify/cn/cli/quality.mdx | 84 ++++ mintlify/cn/cli/substrate.mdx | 103 +++++ mintlify/cn/concepts/config-compiler.mdx | 100 +++++ mintlify/cn/concepts/cross-session-memory.mdx | 85 +++++ mintlify/cn/concepts/model-routing.mdx | 80 ++++ mintlify/cn/concepts/pre-action-gate.mdx | 99 +++++ .../cn/concepts/proof-carrying-memory.mdx | 113 ++++++ mintlify/cn/concepts/verification-gates.mdx | 99 +++++ mintlify/cn/guides/radar-deps.mdx | 67 ++++ mintlify/cn/guides/team-memory.mdx | 79 ++++ mintlify/cn/guides/zero-config-onboarding.mdx | 86 +++++ mintlify/cn/installation.mdx | 105 +++++ mintlify/cn/introduction.mdx | 132 +++++++ mintlify/cn/quickstart.mdx | 106 +++++ mintlify/docs.json | 361 ++++++++++++++++-- mintlify/hi/cli/config.mdx | 91 +++++ mintlify/hi/cli/core.mdx | 77 ++++ mintlify/hi/cli/memory.mdx | 107 ++++++ mintlify/hi/cli/overview.mdx | 61 +++ mintlify/hi/cli/quality.mdx | 84 ++++ mintlify/hi/cli/substrate.mdx | 103 +++++ mintlify/hi/concepts/config-compiler.mdx | 101 +++++ mintlify/hi/concepts/cross-session-memory.mdx | 88 +++++ mintlify/hi/concepts/model-routing.mdx | 80 ++++ mintlify/hi/concepts/pre-action-gate.mdx | 100 +++++ .../hi/concepts/proof-carrying-memory.mdx | 115 ++++++ mintlify/hi/concepts/verification-gates.mdx | 101 +++++ mintlify/hi/guides/radar-deps.mdx | 69 ++++ mintlify/hi/guides/team-memory.mdx | 80 ++++ mintlify/hi/guides/zero-config-onboarding.mdx | 88 +++++ mintlify/hi/installation.mdx | 105 +++++ mintlify/hi/introduction.mdx | 137 +++++++ mintlify/hi/quickstart.mdx | 107 ++++++ mintlify/zh-CN/cli/config.mdx | 86 +++++ mintlify/zh-CN/cli/core.mdx | 69 ++++ mintlify/zh-CN/cli/memory.mdx | 103 +++++ mintlify/zh-CN/cli/overview.mdx | 50 +++ mintlify/zh-CN/cli/quality.mdx | 81 ++++ mintlify/zh-CN/cli/substrate.mdx | 99 +++++ mintlify/zh-CN/concepts/config-compiler.mdx | 80 ++++ .../zh-CN/concepts/cross-session-memory.mdx | 70 ++++ mintlify/zh-CN/concepts/model-routing.mdx | 61 +++ mintlify/zh-CN/concepts/pre-action-gate.mdx | 84 ++++ .../zh-CN/concepts/proof-carrying-memory.mdx | 95 +++++ .../zh-CN/concepts/verification-gates.mdx | 83 ++++ mintlify/zh-CN/guides/radar-deps.mdx | 54 +++ mintlify/zh-CN/guides/team-memory.mdx | 66 ++++ .../zh-CN/guides/zero-config-onboarding.mdx | 80 ++++ mintlify/zh-CN/installation.mdx | 98 +++++ mintlify/zh-CN/introduction.mdx | 99 +++++ mintlify/zh-CN/quickstart.mdx | 97 +++++ mintlify/zh-Hans/cli/config.mdx | 86 +++++ mintlify/zh-Hans/cli/core.mdx | 70 ++++ mintlify/zh-Hans/cli/memory.mdx | 103 +++++ mintlify/zh-Hans/cli/overview.mdx | 55 +++ mintlify/zh-Hans/cli/quality.mdx | 81 ++++ mintlify/zh-Hans/cli/substrate.mdx | 99 +++++ mintlify/zh-Hans/concepts/config-compiler.mdx | 84 ++++ .../zh-Hans/concepts/cross-session-memory.mdx | 73 ++++ mintlify/zh-Hans/concepts/model-routing.mdx | 63 +++ mintlify/zh-Hans/concepts/pre-action-gate.mdx | 86 +++++ .../concepts/proof-carrying-memory.mdx | 97 +++++ .../zh-Hans/concepts/verification-gates.mdx | 83 ++++ mintlify/zh-Hans/guides/radar-deps.mdx | 56 +++ mintlify/zh-Hans/guides/team-memory.mdx | 66 ++++ .../zh-Hans/guides/zero-config-onboarding.mdx | 81 ++++ mintlify/zh-Hans/installation.mdx | 98 +++++ mintlify/zh-Hans/introduction.mdx | 103 +++++ mintlify/zh-Hans/quickstart.mdx | 97 +++++ 91 files changed, 8289 insertions(+), 35 deletions(-) create mode 100644 mintlify/ar/cli/config.mdx create mode 100644 mintlify/ar/cli/core.mdx create mode 100644 mintlify/ar/cli/memory.mdx create mode 100644 mintlify/ar/cli/overview.mdx create mode 100644 mintlify/ar/cli/quality.mdx create mode 100644 mintlify/ar/cli/substrate.mdx create mode 100644 mintlify/ar/concepts/config-compiler.mdx create mode 100644 mintlify/ar/concepts/cross-session-memory.mdx create mode 100644 mintlify/ar/concepts/model-routing.mdx create mode 100644 mintlify/ar/concepts/pre-action-gate.mdx create mode 100644 mintlify/ar/concepts/proof-carrying-memory.mdx create mode 100644 mintlify/ar/concepts/verification-gates.mdx create mode 100644 mintlify/ar/guides/radar-deps.mdx create mode 100644 mintlify/ar/guides/team-memory.mdx create mode 100644 mintlify/ar/guides/zero-config-onboarding.mdx create mode 100644 mintlify/ar/installation.mdx create mode 100644 mintlify/ar/introduction.mdx create mode 100644 mintlify/ar/quickstart.mdx create mode 100644 mintlify/cn/cli/config.mdx create mode 100644 mintlify/cn/cli/core.mdx create mode 100644 mintlify/cn/cli/memory.mdx create mode 100644 mintlify/cn/cli/overview.mdx create mode 100644 mintlify/cn/cli/quality.mdx create mode 100644 mintlify/cn/cli/substrate.mdx create mode 100644 mintlify/cn/concepts/config-compiler.mdx create mode 100644 mintlify/cn/concepts/cross-session-memory.mdx create mode 100644 mintlify/cn/concepts/model-routing.mdx create mode 100644 mintlify/cn/concepts/pre-action-gate.mdx create mode 100644 mintlify/cn/concepts/proof-carrying-memory.mdx create mode 100644 mintlify/cn/concepts/verification-gates.mdx create mode 100644 mintlify/cn/guides/radar-deps.mdx create mode 100644 mintlify/cn/guides/team-memory.mdx create mode 100644 mintlify/cn/guides/zero-config-onboarding.mdx create mode 100644 mintlify/cn/installation.mdx create mode 100644 mintlify/cn/introduction.mdx create mode 100644 mintlify/cn/quickstart.mdx create mode 100644 mintlify/hi/cli/config.mdx create mode 100644 mintlify/hi/cli/core.mdx create mode 100644 mintlify/hi/cli/memory.mdx create mode 100644 mintlify/hi/cli/overview.mdx create mode 100644 mintlify/hi/cli/quality.mdx create mode 100644 mintlify/hi/cli/substrate.mdx create mode 100644 mintlify/hi/concepts/config-compiler.mdx create mode 100644 mintlify/hi/concepts/cross-session-memory.mdx create mode 100644 mintlify/hi/concepts/model-routing.mdx create mode 100644 mintlify/hi/concepts/pre-action-gate.mdx create mode 100644 mintlify/hi/concepts/proof-carrying-memory.mdx create mode 100644 mintlify/hi/concepts/verification-gates.mdx create mode 100644 mintlify/hi/guides/radar-deps.mdx create mode 100644 mintlify/hi/guides/team-memory.mdx create mode 100644 mintlify/hi/guides/zero-config-onboarding.mdx create mode 100644 mintlify/hi/installation.mdx create mode 100644 mintlify/hi/introduction.mdx create mode 100644 mintlify/hi/quickstart.mdx create mode 100644 mintlify/zh-CN/cli/config.mdx create mode 100644 mintlify/zh-CN/cli/core.mdx create mode 100644 mintlify/zh-CN/cli/memory.mdx create mode 100644 mintlify/zh-CN/cli/overview.mdx create mode 100644 mintlify/zh-CN/cli/quality.mdx create mode 100644 mintlify/zh-CN/cli/substrate.mdx create mode 100644 mintlify/zh-CN/concepts/config-compiler.mdx create mode 100644 mintlify/zh-CN/concepts/cross-session-memory.mdx create mode 100644 mintlify/zh-CN/concepts/model-routing.mdx create mode 100644 mintlify/zh-CN/concepts/pre-action-gate.mdx create mode 100644 mintlify/zh-CN/concepts/proof-carrying-memory.mdx create mode 100644 mintlify/zh-CN/concepts/verification-gates.mdx create mode 100644 mintlify/zh-CN/guides/radar-deps.mdx create mode 100644 mintlify/zh-CN/guides/team-memory.mdx create mode 100644 mintlify/zh-CN/guides/zero-config-onboarding.mdx create mode 100644 mintlify/zh-CN/installation.mdx create mode 100644 mintlify/zh-CN/introduction.mdx create mode 100644 mintlify/zh-CN/quickstart.mdx create mode 100644 mintlify/zh-Hans/cli/config.mdx create mode 100644 mintlify/zh-Hans/cli/core.mdx create mode 100644 mintlify/zh-Hans/cli/memory.mdx create mode 100644 mintlify/zh-Hans/cli/overview.mdx create mode 100644 mintlify/zh-Hans/cli/quality.mdx create mode 100644 mintlify/zh-Hans/cli/substrate.mdx create mode 100644 mintlify/zh-Hans/concepts/config-compiler.mdx create mode 100644 mintlify/zh-Hans/concepts/cross-session-memory.mdx create mode 100644 mintlify/zh-Hans/concepts/model-routing.mdx create mode 100644 mintlify/zh-Hans/concepts/pre-action-gate.mdx create mode 100644 mintlify/zh-Hans/concepts/proof-carrying-memory.mdx create mode 100644 mintlify/zh-Hans/concepts/verification-gates.mdx create mode 100644 mintlify/zh-Hans/guides/radar-deps.mdx create mode 100644 mintlify/zh-Hans/guides/team-memory.mdx create mode 100644 mintlify/zh-Hans/guides/zero-config-onboarding.mdx create mode 100644 mintlify/zh-Hans/installation.mdx create mode 100644 mintlify/zh-Hans/introduction.mdx create mode 100644 mintlify/zh-Hans/quickstart.mdx diff --git a/mintlify/ar/cli/config.mdx b/mintlify/ar/cli/config.mdx new file mode 100644 index 0000000..e622a41 --- /dev/null +++ b/mintlify/ar/cli/config.mdx @@ -0,0 +1,91 @@ +--- +title: "أوامر Config" +description: "المزوِّدون، والتكلفة، ولوحات المعلومات، والعلامة التجارية، والأطلس، والحزمة: config وcost وdash وbrand وatlas وstack — إضافةً إلى أمرَي report وtools في الإصدار v0.19+." +--- + +تُغطّي مجموعة Config المزوِّدين، والملاحظة، ورسم الشيفرة، واكتشاف الحزمة. + +## `forge config` + +إعداد المزوِّد — عرض / تبديل / إضافة المزوِّدين، وضبط النموذج الافتراضي. + +```bash +forge config # show current config +forge config switch +forge config add +``` + +## `forge cost` + +الإنفاق الفعلي في اليوم عبر معاملات المراحل المُقاسة. + +```bash +forge cost # real per-day spend +forge cost --stages # measured per-stage cost factors +``` + + + يُبلَّغ عن **المراحل المُقاسة فقط** — المرحلة التي لا أحداث فيها تقول "لا بيانات"، + وليس قيمة افتراضية. + + +## `forge dash` + +لوحة معلومات محلية فوق السجل والقياسات ونصف قطر الانفجار. + +```bash +forge dash # localhost-only, read-only (default port 4242) +``` + +## `forge brand` + +طباعة خريطة رموز العلامة التجارية الفعّالة. + +```bash +forge brand +``` + +تُخزَّن العلامة التجارية كرمز واحد (`brand.json`)؛ إعادة التسمية تعديل واحد فقط. + +## `forge atlas` + +بناء/استعلام رسم الشيفرة. + +```bash +forge atlas build [path] # walk the tree → .forge/atlas.json +forge atlas query "what calls Z" +forge atlas has # hallucinated-symbol check +``` + +الأطلس JSON عادي — أي أداة تقرؤه، ولا حاجة إلى MCP. + +## `forge stack` + +اكتشاف حزمة المستودع الفعلية من ملفات البيانات الوصفية. + +```bash +forge stack +``` + +يقرأ `package.json`، و`pyproject.toml`، و`go.mod`، و`Cargo.toml`، و`Gemfile`، +و`composer.json`، و`pom.xml` / `build.gradle`، و`*.csproj`، ويُبلغ عن اللغات، +وأُطر العمل، ومديري الحِزم، وأوامر الاختبار **الفعلية** للمستودع — التي تُغذّي قائمة +تحقق الركيزة. + +## `forge report` v0.19+ + +توليد تقرير HTML ثابت عن حالة Forge للمستودع — السجل والقياسات ونصف قطر الانفجار +مُصيَّرة في ملف مكتفٍ ذاتيًا يمكنك مشاركته أو أرشفته. + +```bash +forge report +``` + +## `forge tools` v0.19+ + +اختَر أداة الترميز الأساسية بالذكاء الاصطناعي لهذا المستودع، ووصِّل مدخلات `.gitignore` +المطابقة، ليتم تجاهل الإعدادات المُولَّدة وقطع `.forge/` تجاهلًا صحيحًا لإعدادك. + +```bash +forge tools +``` diff --git a/mintlify/ar/cli/core.mdx b/mintlify/ar/cli/core.mdx new file mode 100644 index 0000000..a4e5d43 --- /dev/null +++ b/mintlify/ar/cli/core.mdx @@ -0,0 +1,77 @@ +--- +title: "أوامر Core" +description: "تهيئة المستودع والحفاظ عليه: init وsync وdoctor وcatalog وdocs وupdate." +--- + +تُهيّئ مجموعة Core المستودع وتحافظ على صحته. + +## `forge init` + +بناء إعداد المستودع — يُصدر لكل أداة من مصدر مشترك. + +```bash +forge init +``` + +يُصدر `AGENTS.md`، و`CLAUDE.md`، و`.gemini/settings.json`، و`.aider.conf.yml`، والباقي +(إضافةً إلى إعداد خادم MCP لأدوات Roo Code وVS Code)، وقاعدة الدمج الاتحادي في +`.gitattributes` التي يحتاجها السجل. + +## `forge sync` + +إعادة تصريف المصدر القانوني إلى ملفات الإعداد الأصلية لكل أداة. + +```bash +forge sync +``` + +عديم الأثر — يعيد كتابة ما تغيّر فقط. شغّله بعد تعديل `source/rules.json` أو +`.forge/rules.json` الخاص بالمستودع. + +## `forge doctor` + +فحص صحة الأدوات المثبتة، والحواجز، ومصادقة MCP، وانحراف الإعدادات. + +```bash +forge doctor +``` + +نجاح/إخفاق عبر الأدوات، والحواجز، وتوصيلات MCP، وانحراف الإعدادات، وحالة التحديث. كل +مسار يفشل بلطف. يطبع صف **نماذج البوّابة** التعيين المحلول `tier → model` عند إعداد +بوّابة مخصّصة. + +## `forge catalog` + +ابدأ من هنا — يعرض كل أداة، وطاقم، وحاجز مع سبب موجز من سطر واحد. + +```bash +forge catalog +``` + +## `forge docs` + +انحراف التوثيق ↔ الشيفرة. + +```bash +forge docs check # registry reconcile — commands, env vars, MCP tools, CHANGELOG +forge docs sync # diff-driven stale-docs sweep +``` + + + يفشل `docs check` في CI عندما تنحرف الأوامر، أو متغيرات البيئة، أو أدوات MCP، أو + CHANGELOG عن الشيفرة. يمسح `docs sync` الفرق ويُبلغ عن UPDATED / STALE / + VERIFIED-UNAFFECTED. + + +## `forge update` + +تحديث ذاتي عبر أنماط التثبيت الثلاثة كلها. + +```bash +forge update # apply the update (git checkout or npm/copy install) +forge update --check # report whether a newer version is available +forge update --to # pin or downgrade to a specific version (v0.19+) +``` + +كل مسار يفشل بلطف — دون اتصال أو منبع أو رأس منفصل يُرجَع "غير معروف"، لا خطأ. +`FORGE_NO_UPDATE_CHECK=1` يُسكت إشعار الطبيب. diff --git a/mintlify/ar/cli/memory.mdx b/mintlify/ar/cli/memory.mdx new file mode 100644 index 0000000..07ab1fa --- /dev/null +++ b/mintlify/ar/cli/memory.mdx @@ -0,0 +1,107 @@ +--- +title: "أوامر Memory" +description: "الذاكرة عبر الجلسات وذاكرة الفريق: cortex وrecall وremember وbrain وledger وreuse وhandoff وdecide — تلتقي جميعها في السجل الحامل للإثبات." +--- + +تُدير مجموعة Memory الذاكرة عبر الجلسات وذاكرة الفريق. تلتقي كلها في السجل الحامل +للإثبات تحت `.forge/ledger/`. راجع +[الذاكرة الحاملة للإثبات](/ar/concepts/proof-carrying-memory) للنموذج. + +## `forge cortex` + +ذاكرة مشروع ذاتية التصحيح — دروس مستنبطة من التصحيحات. + +```bash +forge cortex status # what's been learned +forge cortex why # why a lesson applies here +``` + +## `forge recall` + +إدارة الذاكرة الشخصية عبر الجلسات. + +```bash +forge recall list # facts the recall-load guard injects next session +forge recall add "db port" "Postgres is on 5433 here, not 5432" +forge recall consolidate # summarize (advisory, human-reviewable) +``` + +## `forge remember` + +إضافة حقيقة دائمة وقابلة للحفظ في المستودع إلى ذاكرة المستودع المحمولة. + +```bash +forge remember "" +``` + +## `forge brain` + +عرض أو إعادة بناء فهرس ذاكرة المشروع المحمول. + +```bash +forge brain # show the index +forge brain --rebuild # rebuild it +``` + +## `forge ledger` + +الذاكرة الحاملة للإثبات — مخزن الادعاءات المعنون بمحتواه. + +```bash +forge ledger stats # what the repo knows, by kind and trust level +forge ledger verify # re-check claims are in normal form +forge ledger show # a claim and its evidence +forge ledger blame # who minted it, every oracle outcome, per-author trust +forge ledger query "" # retrieve by relevance +forge ledger ratify # human accept +forge ledger retract # tombstone a claim +forge ledger merge # fold a teammate's ledger in, conflict-free +forge ledger import # bridge legacy stores into the ledger +``` + +أضف `--personal` للحصول على سجل خاص بالمستخدم. + +## `forge reuse` + +مخبأ شيفرة حامل للإثبات — يُقدَّم فقط عندما تظل أدلته صالحة. + +```bash +forge reuse query "" # verified code you already have +forge reuse mint "" --file # add an artifact to the cache +forge reuse stats # cache stats +``` + +## `forge handoff` + +لقطة جلسة محدودة — تُعيد كتابة `.forge/state.md`، وتُحقن في بداية كل جلسة. + +```bash +forge handoff "" --next "" +``` + +## `forge decide` + +سجل قرارات إضافي فقط — إدخالات ADR-lite بصيغة `D-####` في `.forge/decisions.md`. + +```bash +forge decide " — " +forge decide # read the log before re-deciding +``` + +## `forge know` v0.19+ + +توجيه حقيقة إلى موطن تخزينها الصحيح — يقرر ما إذا كانت المعرفة تنتمي إلى +`recall`، أو `remember`/`brain`، أو قرار، أو درس cortex، ويودعها هناك. + +```bash +forge know "" +``` + +## `forge deja` v0.19+ + +بحث عن أعمال سابقة مماثلة — يُظهر الأعمال السابقة في السجل التي تشبه ما توشك على +عمله، لتعيد استخدام الإثبات بدلًا من التوليد من جديد. + +```bash +forge deja "" +``` diff --git a/mintlify/ar/cli/overview.mdx b/mintlify/ar/cli/overview.mdx new file mode 100644 index 0000000..3d073f3 --- /dev/null +++ b/mintlify/ar/cli/overview.mdx @@ -0,0 +1,60 @@ +--- +title: "نظرة عامة على CLI" +description: "كل أمر من أوامر forge مُصنَّف حسب المجموعات Core وMemory وSubstrate وQuality وConfig — سطح الأوامر بيانات، ويتم توفيقه مع التوثيق بفحص انحراف صارم." +--- + +يُعرَّف سطح أوامر `forge` كبيانات (`src/commands.js`)، ويتم توفيقه مع التوثيق عبر +`forge docs check`، بحيث لا يستطيع أمر أن يُشحن أو يختفي دون أن يلاحظه التوثيق. تُنظَّم +الأوامر في خمس مجموعات. + + + + التهيئة والصيانة: `init`، و`sync`، و`doctor`، و`catalog`، و`docs`، و`update`. + + + الذاكرة عبر الجلسات وذاكرة الفريق: `cortex`، و`recall`، و`remember`، و`brain`، + و`ledger`، و`reuse`، و`handoff`، و`decide`. + + + بوّابة ما قبل الفعل ومراحلها: `substrate`، و`preflight`، و`route`، و`impact`، + و`scope`، و`context`، و`anchor`، و`diagnose`، و`imagine`، و`lean`. + + + التحقق والسلامة: `verify`، و`scan`، و`spec`، و`taste`، و`uicheck`، و`harden`. + + + المزوِّدون، والتكلفة، ولوحات المعلومات، والعلامة التجارية، والأطلس، والحزمة: + `config`، و`cost`، و`dash`، و`brand`، و`atlas`، و`stack`. + + + +## الاصطلاحات + +- **إرشادي افتراضيًا.** اضبط `FORGE_ENFORCE=1` لتحويل الركيزة إلى حجب صارم على أقوى + الإشارات (طلب فارغ، سياق مطلوب غير قابل للتجميع، نصف قطر انفجار يتجاوز عتبة + 25 ملفًا الافتراضية). +- **صامت افتراضيًا.** العنوان `Forge — …` لكل أمر هو زينة علامة تجارية خلف + `--verbose` / `FORGE_VERBOSE`؛ يُصدر الأمر نتيجته أولًا. +- **مخرَجات ملائمة للأنبوب.** نص عادي عند الأنبوب؛ في الطرفية يضيف ألوان لوحة العلامة + التجارية ومقاييس الثقة. `NO_COLOR` يوقف اللون، `FORCE_COLOR=1` يُفرضه. +- **`--json`** متاح للركيزة ومعظم أوامر التحليل للسكربتات. + + + شغّل `forge --help` للقائمة المحدَّثة دائمًا، أو `forge catalog` لفهرس البدء لكل + أداة وطاقم وحاجز مع سبب موجز. + + +## جديد في v0.19+ + +عدة أوامر وعلامات تصل في خط v0.19. موثقة في صفحات مجموعاتها وموسومة داخل النص: + +| الأمر / العلامة | المجموعة | ماذا يفعل | +| ---------------------- | -------- | ----------------------------------------------- | +| `forge know` | Memory | توجيه حقيقة إلى موطن تخزينها الصحيح. | +| `forge deja` | Memory | بحث عن أعمال سابقة مماثلة. | +| `forge precommit` | Quality | بوّابة تحقق على مستوى الالتزام. | +| `forge radar` | Quality | حلقات حداثة التبعيات. | +| `forge report` | Config | تقرير HTML ثابت عن حالة Forge للمستودع. | +| `forge tools` | Config | اختيار الأداة الأساسية + توصيل gitignore. | +| `forge verify --deep` | Quality | تحقق بإجماع متعدد العدسات. | +| `forge update --to` | Core | التثبيت أو الرجوع إلى إصدار معيّن. | diff --git a/mintlify/ar/cli/quality.mdx b/mintlify/ar/cli/quality.mdx new file mode 100644 index 0000000..cf41f46 --- /dev/null +++ b/mintlify/ar/cli/quality.mdx @@ -0,0 +1,84 @@ +--- +title: "أوامر Quality" +description: "التحقق والسلامة: verify وscan وspec وtaste وuicheck وharden — إضافةً إلى بوّابتَي precommit وradar في الإصدار v0.19+." +--- + +مجموعة Quality هي سطح التحقق والسلامة. راجع +[بوّابات التحقق](/ar/concepts/verification-gates) لكيفية تركيبها. + +## `forge verify` + +بوّابة تحقق مستقلة — اختبارات + رمز مُهلوَس + مصدرية. + +```bash +forge verify +forge verify --deep # multi-lens consensus (v0.19+) +``` + +## `forge scan` + +بوّابة المهارات — فحص مهارة أو خادم MCP بحثًا عن الحقن / RCE / التسريب قبل التثبيت. + +```bash +forge scan +``` + +## `forge spec` + +المواصفة كعقد — init (OpenSpec)، وقفل، وفحص الانحراف. + +```bash +forge spec init +forge spec lock +forge spec check +``` + +## `forge taste` + +تمكين أداة ذوق واحدة لواجهة المستخدم لهذا المستودع (بدون وسيط يعرض الخيارات). + +```bash +forge taste # list the profiles +forge taste # brutalist · corporate · editorial · minimalist · playful +``` + +يكتب `DESIGN.md` ويُعدّل عتبات بوّابة `uicheck design`. + +## `forge uicheck` + +فحوصات حتمية لواجهة المستخدم. + +```bash +forge uicheck contrast # WCAG contrast ratio +forge uicheck fingerprint # deterministic design fingerprint +forge uicheck design # slop-distance + conformance gate +forge uicheck visual # Playwright-rendered check (opt-in tier) +``` + +## `forge harden` + +توصيل ضوابط الأمان — gitleaks قبل الالتزام + إعدادات الصندوق الرملي. + +```bash +forge harden +``` + +## `forge precommit` v0.19+ + +بوّابة على مستوى الالتزام — تُشغّل الحد الأدنى للتحقق عند وقت الالتزام، فيُلتقط +العمل الجزئي أو غير المُتحقَّق منه قبل أن يستقر. + +```bash +forge precommit +``` + +## `forge radar` v0.19+ + +حلقات حداثة التبعيات — تُجمِّع تبعيات المشروع بحسب مدى حداثتها، ليظهر ما هو بائت أو +منحرف قبل أن يعضّ. + +```bash +forge radar +``` + +راجع دليل [إبقاء التبعيات محدَّثة](/ar/guides/radar-deps) لكيفية قراءة الحلقات. diff --git a/mintlify/ar/cli/substrate.mdx b/mintlify/ar/cli/substrate.mdx new file mode 100644 index 0000000..4e72566 --- /dev/null +++ b/mintlify/ar/cli/substrate.mdx @@ -0,0 +1,103 @@ +--- +title: "أوامر Substrate" +description: "بوّابة ما قبل الفعل ومراحلها القابلة للاستدعاء فرديًا: substrate وpreflight وroute وimpact وscope وcontext وanchor وdiagnose وimagine وlean." +--- + +مجموعة Substrate هي بوّابة ما قبل الفعل. يُركّب `forge substrate` بقية المراحل في حكم +واحد؛ وكل مرحلة قابلة للاستدعاء بمفردها. راجع +[بوّابة ما قبل الفعل](/ar/concepts/pre-action-gate) للحصول على الأنبوب. + +## `forge substrate` + +بوّابة ما قبل الفعل الواحدة: الافتراضات، والتوجيه، والأثر، والنطاق، والذاكرة، والتحقق. + +```bash +forge substrate "" +forge substrate "" --json +``` + +إذا أرجع `okToProceed:false`، اسأل `assumption.questions` المُرجَعة قبل التعديل. + +## `forge preflight` + +فحص الافتراضات — ما تُسمّيه المهمة ولا يُعرِّفه المستودع. + +```bash +forge preflight "" +``` + +## `forge route` + +اقتراح أرخص نموذج قادر على المهمة. + +```bash +forge route "" +forge route gateway # emit LiteLLM gateway config +``` + +## `forge impact` + +توقّع نصف قطر الانفجار لرمز أو ملف من رسم الأطلس. + +```bash +forge impact +``` + +## `forge scope` + +تفكيك الملفات إلى عناقيد مستقلة — إضافةً إلى الملفات المترابطة التي لم تسمِّها. + +```bash +forge scope +``` + +## `forge context` + +تجميع سياق موزون بميزانية + بوّابة اكتمال — ما يحتاج التعديل أن يُعرف. + +```bash +forge context "" +``` + +يُجمّع سياقًا موزونًا بميزانية عبر تغطية مجموعة (set-cover) فوق مجموعة التعديل المتوقعة، +ويُطبّق سلم ضغط، ويُبلغ عن مجموعة المفقودات المحسوبة. + +## `forge anchor` + +فحص انحراف الهدف — هل ما زالت تغييراتك الفعلية (في git) على الهدف المُعلن؟ + +```bash +forge anchor set "" # persist the goal across sessions +forge anchor show +forge anchor clear +``` + +## `forge diagnose` + +فحص الحلقة الهالكة — سجِّل إخفاقًا؛ فالتوقيع نفسه 3× يولّد تشخيصًا + تصعيدًا. + +```bash +forge diagnose "" +``` + +## `forge imagine` + +محاكاة العواقب — أعطال متوقعة + الحد الأدنى من مجموعة الاختبارات (dry-run) لمهمة. + +```bash +forge imagine "" +forge imagine "" --run # execute the minimal suite sandboxed +``` + +## `forge lean` + +الحد الأدنى للنطاق (M5) — قياس بصمة الفرق مقابل ما طلبته المهمة. + +```bash +forge lean +``` + + + تعمل مراحل `route` و`impact` و`scope` و`context` و`anchor` و`lean` كلها داخل + `forge substrate`. استدعِها فرديًا حين ترغب في إشارة واحدة فقط. + diff --git a/mintlify/ar/concepts/config-compiler.mdx b/mintlify/ar/concepts/config-compiler.mdx new file mode 100644 index 0000000..76a0e26 --- /dev/null +++ b/mintlify/ar/concepts/config-compiler.mdx @@ -0,0 +1,97 @@ +--- +title: "مُصرِّف الإعدادات رباعي الطبقات" +description: "اكتب الركيزة مرة واحدة؛ يُصرِّفها forge sync إلى الإعداد الأصلي لكل أداة. الطبقات الأربع هي كيف يُعبَّر عن الدماغ؛ والمُصرِّف هو كيف يُوصَل." +--- + +تكتب الركيزة مرة واحدة. يُصرِّف `forge sync` هذا المصدر إلى الإعداد الأصلي لكل أداة. +الطبقات الأربع هي _كيف يُعبَّر عن الدماغ_؛ والمُصرِّف هو _كيف يُوصَل_. + +```mermaid +flowchart TD + S["source/ · rules.json · substrate.json · mcp.json"] -->|"forge sync — content-hash + DO-NOT-EDIT headers"| N["native configs · CLAUDE.md · AGENTS.md · .cursor · .gemini · .aider"] + S -. configures .-> L + subgraph L["the four layers"] + direction LR + T["tools · model-invoked skills"] + C["crew · isolated sub-agents"] + G["guards · deterministic hooks"] + M["mcp · atlas + substrate server"] + end +``` + +## مصدر واحد، مُصدِرات عديدة + +اكتب القواعد **مرة واحدة** (`source/rules.json`)؛ يُصدر مُصرِّف حتمي (`forge sync`) +الصيغة الأصلية لكل أداة بترويسة تجزئة للمحتوى، فيصبح الانحراف قابلًا للكشف وإعادة +التشغيل بلا أثر. لا تُكتب قاعدة مرتين أبدًا. المصدر القانوني ثلاثة ملفات: + +| ملف المصدر | ما يحويه | +| ----------------------- | -------------------------------------------------------------------- | +| `source/rules.json` | القواعد الهندسية القانونية (git، الاختبارات، الأمن، الأسلوب). | +| `source/substrate.json` | الإعدادات الافتراضية للركيزة المعرفية — العتبات، والتوجيه، ومقابض LLM. | +| `source/mcp.json` | تعريفات خوادم MCP التي تُصدر لكل أداة. | + +## الطبقات الأربع + +كل طبقة لها اسم علامة تجارية وتُصدر عبر الأدوات. + + + + `~/.forge/tools/` → `~/.claude/skills/`. مهارات يستدعيها النموذج، تتبع معيار + `SKILL.md` (بيانات وصفية `name` + `description`). + + + `~/.forge/crew/` → `~/.claude/agents/`. وكلاء فرعيون معزولون السياق، مثل + الاستكشاف، والتحقق، والتحقق الأمامي. + + + `~/.forge/guards/` → خطّافات `settings.json`. **الطبقة الوحيدة التي _تُنفِّذ_ بدلًا + من الاقتراح.** الحاجز خطّاف حتمي لا يستطيع النموذج الانحراف عنه. تُعترف القواعد + النصية في `CLAUDE.md` ثم تُنسى بعد الضغط؛ الحاجز لا يُنسى. كل ثابت قابل للتنفيذ + ينتمي هنا. + + + يشحن Forge خادم stdio واحدًا (`src/cortex_mcp.js`) يعرض 19 أداة MCP: فحوصات + الركيزة (`substrate_check` / `predict_impact` / `assumption_gate` / …)، + قراءات _وكتابات_ الذاكرة (`forge_remember`، ledger ratify/retract)، والصحة. + + + +تخترق الشواغل العابرة الطبقات الأربع كلها: **atlas** (رسم الشيفرة)، و**lean** +(الحد الأدنى — يُشحن كأداة وكحاجز إيقاف، فيسري سواء استدعاه النموذج أم لا)، و**recall** +(الذاكرة). + +## الحاجز فوق النص + +القواعد التي يمكن للنموذج الانحراف عنها تعيش في النص؛ والقواعد التي **لا يجوز له** +كسرها تعيش في الحواجز (خطّافات shell حتمية). لا يمكن نسيان الحاجز بعد ضغط السياق. + + + انقل كل ثابت قابل للتنفيذ من `CLAUDE.md` إلى حاجز؛ واحتفظ بالنص رقيقًا. هذا هو + أهم انضباط منفرد في تصميم Forge. + + +## مصفوفة الإصدار المتحقق منها عبر الأدوات + +يُصدر Forge إعدادات لـ **تسع أدوات**، إضافةً إلى خادم MCP لأدوات Roo Code وVS Code. +كل صف مُوثَّق بالرجوع إلى وثائق المورّد. + +| الأداة | الهدف الأصلي | كيف يُصدر Forge | +| ------------------ | ---------------------------------------------------------------- | --------------------------------------------------------------------- | +| **Claude Code** | `CLAUDE.md` (+ `.claude/rules/*.md`، `settings.json`) | `CLAUDE.md` رقيق يبدأ سطره الأول بـ `@AGENTS.md`؛ الحواجز → settings | +| **Codex** | `AGENTS.md` أصلي (سقف 32 KiB) | `AGENTS.md` القانوني في الجذر **هو** المصدر | +| **Cursor** | `AGENTS.md` + `.cursor/rules/*.mdc` | `AGENTS.md` للقواعد المسطحة؛ `.mdc` عند الحاجة إلى نطاق | +| **Gemini** | `GEMINI.md`، أو `AGENTS.md` عبر تفعيل `context.fileName` | يكتب `.gemini/settings.json` لتفادي نسخة ثانية | +| **Aider** | `CONVENTIONS.md` عبر `read:` في `.aider.conf.yml` | يُصدر `.aider.conf.yml` مع `read: AGENTS.md` | +| **Copilot** | `AGENTS.md` في الجذر + `.github/copilot-instructions.md` | يعتمد على `AGENTS.md` في الجذر؛ مؤشر `.github` اختياري | +| **Windsurf/Devin** | `AGENTS.md` مكتشَف تلقائيًا (سقف 6k/12k حرفًا) | `AGENTS.md` جذري تحت الحد؛ يميز بين `.windsurf` و`.devin` | +| **Zed** | أول مطابقة من قائمة أولوية تشمل `AGENTS.md` | يُصدر `AGENTS.md`؛ يُشير الطبيب لأي ملف قديم مُظلِّل | +| **Continue** | `.continue/rules/*.md` + `.continue/mcpServers/*.yaml` | يُصدر ملف قواعد + إعداد خادم Forge MCP | + +تتلقّى Roo Code وVS Code خادم Forge MCP عبر `forge init` (`.roo/mcp.json`، +`.vscode/mcp.json`) بدلًا من ملف قواعد. + + + **حدود عدد المحارف حقيقية.** يبتر Codex عند 32 KiB، وWindsurf عند 6k/12k. يفرض + `forge sync` ميزانية حجم للمصدر بحيث لا يُبتر إعداد بصمت. + diff --git a/mintlify/ar/concepts/cross-session-memory.mdx b/mintlify/ar/concepts/cross-session-memory.mdx new file mode 100644 index 0000000..981e9d9 --- /dev/null +++ b/mintlify/ar/concepts/cross-session-memory.mdx @@ -0,0 +1,86 @@ +--- +title: "الذاكرة عبر الجلسات" +description: "تثبيت الجلسة، وبوّابة الإكمال، ولقطات التسليم، وسجل القرارات — الطبقة التي تقتل فقدان ذاكرة الجلسة والعمل الجزئي." +--- + +نمطان من الإخفاق تُوجد هذه الطبقة لتقتلهما: **العمل الجزئي** (تغييرات في الشيفرة دون +القطع التي تعتمد عليها) و**فقدان ذاكرة الجلسة** (الجلسة التالية تعيد افتراض ما عرفته +هذه الجلسة). التعليمات ترفع _احتمال_ السلوك الصحيح؛ والخطّافات الحتمية تضمن _حدًّا +أدنى_. + +## تثبيت الجلسة + +عند `SessionStart` (`src/session.js`)، يسجل Forge `HEAD` مرة واحدة لكل جلسة، ويُقلّم +قطع الجلسات الأقدم من أسبوع، ويحقن توجيهًا طازجًا: + + + + دروس Cortex المستنبطة من التصحيحات الماضية. + + + الهدف المُعلن، بحيث يمكن قياس الانحراف مقابله. + + + ملف `.forge/state.md` المحدود الذي كتبته الجلسة السابقة. + + + أحدث الالتزامات والتغييرات غير المُلتزَم بها — أدلة لا افتراضات. + + + +تتوجّه الجلسة الجديدة بالأدلة، لا بالافتراضات المسبقة. + +## بوّابة الإكمال + +الحاجز الوحيد الذي قد يُجيب على مسار Stop هو `completion-gate.sh` +(`src/gate.js`). يعمل بشكل متزامن؛ يظل `cortex.sh stop` الخاص بتنقيب الدروس +منفصلًا ولا يستطيع الحجب أبدًا. + +مجموعة التغييرات محدودة بالجلسة: الملفات من الالتزامات التي زمن مُلتزمها عند بداية +الجلسة أو بعدها، إضافةً إلى تغييرات شجرة العمل ناقصًا الأوساخ المُلتقطة عند +`SessionStart` — بحيث لا تُلصَق التعديلات السابقة، وتبديل الفروع، و`git pull` بالوكيل. + + + إذا تحرّكت الشيفرة دون أن يتبعها توثيق أو أثر حالة، تحجب البوّابة **مرة واحدة** مع + قائمة إصلاح كسبب. كل حالة أخرى تسمح، وكل خطأ داخلي يسمح (فشل بلطف). + `FORGE_STOPGATE=0` يوقفه. + + +قائمة الإصلاح تُشير إلى الأدوات التي تُنهي العمل: + +```bash +forge docs sync # sweep the diff for stale doc mentions +forge handoff "" --next "" # write the bounded session snapshot +forge decide " — " # record a choice so no session re-decides it +``` + +## التسليم والقرارات + +مخزنان يحفظان المعرفة عبر الجلسات: + +| المخزن | الدلالة | +| -------------------- | ------------------------------------------------------------------------------------ | +| `.forge/state.md` | **إعادة كتابة** محدودة (لقطة) — تكلفة التحميل تبقى `O(bound)` إلى الأبد. | +| `.forge/decisions.md`| **ADR-lite** إضافي فقط (`D-####`) مع توأم آلي القراءة لسجل القرارات. | + +كلاهما يرفض الأسرار عند الكتابة. يُعاد حقن `state.md` عند بداية كل جلسة؛ ويُقرأ +`decisions.md` قبل إعادة تقرير أي شيء استقرّت عليه جلسة سابقة. + +```bash +forge handoff "" --next "" +forge decide " — " +forge decide # read the log before re-deciding +``` + +## مسح التوثيق المدفوع بالفرق + +يُجيب `forge docs sync` عن السؤال ذي الشكل الفرقي: المعرِّفات المُغيَّرة (المسارات، +والتعاريف، والرموز المُستدعاة، من الأسطر المضافة _والمحذوفة_) مقابل كل قطعة توثيق +→ UPDATED / STALE (مع إصابات file:line) / VERIFIED-UNAFFECTED، مع تسجيل السبب. هو +مُبلِّغ محض؛ بوّابة الإكمال توفر الأسنان. + + + `recall` و`cortex` ذاكرة ملفات وطلبات فقط — **ليست** تعلمًا على مستوى الأوزان. + التجميع مُلخِّص قد يُهلوس، لذا يبقى إرشاديًا وقابلًا لمراجعة الإنسان وخاليًا من + الأسرار. + diff --git a/mintlify/ar/concepts/model-routing.mdx b/mintlify/ar/concepts/model-routing.mdx new file mode 100644 index 0000000..aca2fbe --- /dev/null +++ b/mintlify/ar/concepts/model-routing.mdx @@ -0,0 +1,78 @@ +--- +title: "توجيه النماذج" +description: "معيار حتمي وقابل للمقارنة (diffable) يختار أرخص فئة نموذج قادرة قبل الإرسال — مع إعادة تعيين آمنة للفشل لبوابات المستضافة ذاتيًا." +--- + +يوصي Forge بأرخص نموذج قادر على تنفيذ مهمة ما **قبل** الإرسال، وذلك من خلال معيار حتمي +يمكنك قراءته في المستودع (`src/model_tiers.json`). على عكس البوابة التي تتخذ القرار +داخل الوكيل (proxy) وقت الطلب، فإن قرار التوجيه هنا مرئي وقابل للمقارنة في git. + +## التوصية بفئة — `forge route` + +```bash +forge route "" # cheapest capable model tier for the task +forge route gateway # emit LiteLLM gateway config +``` + +التوصية عبارة عن حسابات k-NN مبنية على أمثلة نموذجية فوق بنك موسوم (صفوف بالإنجليزية ++ Hinglish) وفق مقياس تشابه بالتداخل مع بوابة ثقة — وليست مجرد بحث بالكلمات المفتاحية. + + + ابدأ من `route.tier` الموصى به ولا تصعّد إلا بعد فشل مُحقِّق خارجي، لا بشكل استباقي أبدًا. + هذا يبقي الإنفاق منخفضًا دون تقييد القدرة عندما تحتاج المهمة إليها فعلًا. + + +## النية أولًا، ثم الفئة + +يشترك التوجيه في الحسابات مع اكتشاف النية (`src/intent.js`): يُطابَق الموجّه (prompt) مع +نية معينة عبر مقدِّر k-NN القائم على الأمثلة النموذجية ذاته. لاحظ أن الاثنين يستخدمان +مجموعات إيقاف مختلفة — التوجيه يعامل الأفعال العامة (`fix` / `add` / `build`) +كضوضاء تعقيد، بينما هذه الأفعال بالضبط هي إشارة النية. + +## جدول الفئات + +يُثبِّت جدول الفئات (`src/model_tiers.json`) معرفات نماذج Anthropic العامة حسب العائلة +(haiku / sonnet / opus / fable). تُوفَّق أسعار المستندات مع هذا الملف عبر فحص المستندات، +بحيث لا يمكن أن ينحرف النص عن الجدول. + +## إعادة التعيين للبوابات المستضافة ذاتيًا + +بوابة LiteLLM أو وكيل مستضاف ذاتيًا يقدّم أسماء نماذجه الخاصة، لذا فإن إرسال معرف قياسي +حرفيًا سيؤدي إلى خطأ 404. عند تكوين عنوان URL أساسي لبوابة غير افتراضية، يقوم Forge +(`src/gateway_model_map.js`) بجلب `GET /v1/models` **مرة واحدة لكل عملية** ويسجّل نقاطًا +لكل معرف مُعلَن مقابل عائلة كل فئة: + + + + يجب أن تتطابق كلمة العائلة (haiku / sonnet / opus / fable) — وهي بوابة صارمة. + + + ضمن العائلة، يختار معامل `setOverlap` لرموز اسم الفئة أفضل تطابق. + + + يُحسم التعادل لصالح المعرف الأقرب إلى الاسم القانوني. + + + + + تستشير إعادة التعيين البوابة **فقط** عندما يكون المعرف المُحلَّل معرفًا _قياسيًا_ — لا يتم + المساس أبدًا باسم مستعار صريح في `.forge/providers.json` أو تجاوز `ANTHROPIC_MODEL`. + يفشل بأمان إلى المعرف القياسي عند غياب البوابة، أو تعذر الوصول إلى `/v1/models`، + أو عدم وجود تطابق عائلي، وبذلك يكون المستخدمون المباشرون لـ `api.anthropic.com` + متطابقين بايتًا ببايت. + + +يطبع صف **gateway models** في `forge doctor` تعيين `tier → model` المُحَل للتحقق. + +## المزودون والتكلفة + +```bash +forge config # show / switch / add providers, set the default model +forge cost # real per-day spend +forge cost --stages # measured per-stage cost factors +``` + + + يُبلِّغ `forge cost --stages` عن **المراحل المُقاسة فقط** — المرحلة التي لا تحتوي على + أحداث تقول "no data"، ولا تعرض قيمة افتراضية أبدًا. أي رقم يظل افتراضًا حتى يُقاس. + diff --git a/mintlify/ar/concepts/pre-action-gate.mdx b/mintlify/ar/concepts/pre-action-gate.mdx new file mode 100644 index 0000000..69b9056 --- /dev/null +++ b/mintlify/ar/concepts/pre-action-gate.mdx @@ -0,0 +1,100 @@ +--- +title: "بوابة ما قبل الإجراء" +description: "يُشغّل forge substrate تمريرة مرتبة واحدة من الفحوصات قبل أن يعدّل النموذج الشيفرة ويعيد حكمًا واحدًا — الافتراضات، والتوجيه، والتأثير، والنطاق، والذاكرة، والتحقق." +--- + +**الركيزة الإدراكية (Cognitive substrate)** — الطبقة التي تعمل _قبل_ أن يعدّل النموذج الشيفرة. +يُشغّل `forge substrate ""` (وأداة MCP المسماة `substrate_check`) تمريرة مرتبة واحدة +من الفحوصات ويعيد حكمًا واحدًا. تُركّب هذه البوابة المراحل القابلة للاستدعاء بشكل مستقل — +`preflight`، `route`، `atlas`، `impact`، `reuse`، `context`، `scope`، `lean`، `anchor`، +`verify` — في عقد واحد لما قبل الإجراء. + +```mermaid +flowchart TD + RE["referenced entities"] --> INTAKE + subgraph INTAKE["intake"] + direction LR + PF["preflight · assumption gap"] --> RT["route · cheapest tier"] + end + INTAKE --> ANALYSIS + subgraph ANALYSIS["analysis"] + direction LR + AT["atlas · code graph"] --> IM["impact · blast radius"] --> PT["predict · failing tests"] --> RU["reuse · cache hit?"] + end + ANALYSIS --> SAFETY + subgraph SAFETY["safety + fit"] + direction LR + CX["context · completeness gate"] --> SC["scope · coupled files"] --> ME["memory · recall + lessons"] --> MN["minimality · lean footprint"] --> GA["goal-anchor · drift check"] + end + SAFETY --> VD["verdict"] +``` + +## المراحل الثلاث + + + + يجد **preflight** فجوة الافتراضات — ما تسميه المهمة ولم يُعرَّف في المستودع. + يختار **route** أرخص فئة نموذج قادرة. + + + يقرأ **atlas** الرسم البياني للشيفرة، ويحسب **impact** نصف قطر الانفجار، + ويسمّي **predict** الاختبارات المرجّح فشلها، ويتحقق **reuse** من وجود ضربة تخزين مؤقت + مُتحقَّق منها. + + + يُشغّل **context** بوابة الاكتمال، ويُظهر **scope** الملفات المقترنة، وتُحقن + **memory** الاستدعاء + الدروس، ويقيس **minimality** البصمة الرشيقة، + ويفحص **goal-anchor** الانحراف. + + + +## نصف قطر الانفجار + +**نصف قطر الانفجار (Blast radius)** — مجموعة الملفات التي يُتوقع أن يؤثر عليها التعديل، +مقروءةً من الرسم البياني للشيفرة. يحسبه `forge impact`؛ ويكشفه خط الأنابيب قبل أن يمس +النموذج أي شيء. + +```bash +forge impact verifyToken # predicted impacted files for a symbol +forge impact src/auth.js # …or for a file +``` + +## استشاري بشكل افتراضي + +الحكم **استشاري بشكل افتراضي** — يُبلِّغ ولا يحجب. عيّن `FORGE_ENFORCE=1` لتحويل +أقوى الإشارات إلى حجب صارم: + + + + لم يجد preflight نية قابلة للتنفيذ — مهمة غير محددة بشكل كافٍ. + + + لا تستطيع بوابة الاكتمال تغطية مجموعة التعديلات المتوقعة. + + + تتجاوز مجموعة الملفات المتأثرة عتبة الافتراضية ~25 ملفًا. + + + +كل شيء آخر يظل تحذيرًا يمكن للإنسان تجاوزه. + + + على Claude Code تعمل البوابة بأكملها **على كل موجّه تلقائيًا** عبر خطاف `UserPromptSubmit` — + صامتة في المهام النظيفة. يقدم `forge substrate "" --json` الحكم القابل للقراءة آليًا + لأغراض البرمجة النصية. + + +## كيف تشغّلها + +```bash +forge substrate "Change verifyToken in src/auth.js to require length > 20; update tests" +forge substrate "" --json +``` + +إذا كان الحكم `ASK FIRST`، فاسأل الأسئلة الواردة في `assumption.questions` قبل التعديل — +لا تخمّن مهمة غير محددة بشكل كافٍ. ابدأ من `route.tier` الموصى به ولا تصعّد إلا بعد فشل +مُحقِّق خارجي، لا استباقيًا أبدًا. + + + تقرأ مرحلة الذاكرة من السجل الحامل للإثبات. + diff --git a/mintlify/ar/concepts/proof-carrying-memory.mdx b/mintlify/ar/concepts/proof-carrying-memory.mdx new file mode 100644 index 0000000..33d47b8 --- /dev/null +++ b/mintlify/ar/concepts/proof-carrying-memory.mdx @@ -0,0 +1,109 @@ +--- +title: "الذاكرة الحاملة للإثبات" +description: "كل حقيقة أو درس أو أثر إعادة استخدام مُخزَّن هو ادعاء يحمل دليله الخاص — ولا يُوثَق به إلا بعد أن ترفع أدوات تحقق مستقلة ثقته فوق حد أدنى." +--- + +**الذاكرة الحاملة للإثبات (Proof-carrying memory أو PCM)** — كل حقيقة أو درس أو أثر إعادة استخدام +مُخزَّن هو _ادعاء_ يحمل دليله الخاص. ولا يُوثَق به إلا بعد أن ترفع أدوات تحقق مستقلة +(اختبارات، CI، قبول/تراجع بشري) ثقتَه فوق حد أدنى. الدرس الخاطئ يضمحل بدلًا من أن يتحجّر. + + + "الذاكرة الحاملة للإثبات" هو اسمنا لـ **ذاكرة مرجعية بالأدلة ومُعنونة بالمحتوى** — ادعاء يُعنون + بتجزئة (hash) محتواه ويُربط بنتائج أدوات التحقق التي تدعمه. "الإثبات" هو مسار الأدلة هذا + مضافًا إليه قاعدة الثقة، **وليس إثباتًا رسميًا مُتحقَّقًا آليًا**؛ لا يوجد مثبت نظريات في الحلقة. + + +## مخزن واحد، كتّاب متعددون + +تلتقي كل أنظمة الذاكرة الفرعية في مخزن واحد. تكتب `recall`، و`remember`/`brain`، +ودروس `cortex`، وآثار `reuse`، ونتائج `diagnose` للحلقة المكسورة جميعها ادعاءات مُعنونة +بالمحتوى في `.forge/ledger/`. + +```mermaid +flowchart LR + subgraph EV["local events"] + direction TB + E1["recall / remember"] + E2["cortex lesson"] + E3["reuse mint"] + E4["diagnose"] + end + EV -->|"content-addressed claims"| LG["(.forge/ledger)"] + O["independent oracles · tests · CI · human accept/revert"] -->|"append evidence · move confidence"| LG + TM["teammate ledgers"] <-->|"git union-merge · conflict-free"| LG + LG --> RV["merged read view · recall list · lesson inject · brain index"] +``` + +## لماذا يتلاقى دون تعارضات + +لأن بايتات الادعاء هي دالة صرفة من `(kind, body, scope)`، فإن كل نسخة تحسب نفس الهوية — +لذا تُطوى سجلات زملاء الفريق معًا فوق git العادي دون أي تعارض. + +ميكانيكيًا: + +- **الأدلة وشواهد القبور (tombstones) قابلة للإلحاق فقط**، وهي سجلات مُزالة التكرار عبر التجزئة. +- **الثقة (`val`)** هي احتمال بايزي لاحق (Beta posterior) مُتحلِّل، ولا تحرّكه سوى أدوات التحقق. +- **الدمج هو شبكة نصف اتصال (join-semilattice)** — مُختبَرة بخصائص تُثبت أنها تبادلية، + وتجميعية، وعديمة القوة (idempotent) — فتتلاقى السجلات بأي ترتيب. + + + يُصدر `forge init` قاعدة `.gitattributes` الخاصة بدمج الاتحاد (union-merge) التي يحتاجها السجل؛ + ويطوي `forge ledger merge ` أي شجرة سجل أخرى. القرار الكامل موثق في ADR-0006 + (proof-carrying memory). + + +## أدوات التحقق تحرّك الثقة — ولا شيء آخر + +فقط أدوات التحقق المستقلة يمكنها تحريك ثقة الذاكرة: + + + + اختبار ناجح يمارس الادعاء يرفع ثقته. + + + خط أنابيب أخضر هو دليل مستقل على أن الادعاء لا يزال قائمًا. + + + قبول صريح أو تراجع هو الإشارة الأقوى من الجميع. + + + +الأدلة غير القابلة للتحقق يرفضها جدول `ORACLES` مغلق (`src/ledger.js`). المعرفة غير المُراجَعة +تضمحل نحو _عدم اليقين_، وليس الحذف — تُحفظ الادعاءات الخاملة للتدقيق، ولا تُزال بصمت أبدًا. + +## واجهة السجل + +```bash +forge ledger stats # what the repo knows, by kind and trust level +forge ledger verify # re-check claims are in normal form +forge ledger show # a claim and its evidence trail +forge ledger blame # who minted it, every oracle outcome, per-author trust +forge ledger query "" # retrieve claims by relevance +forge ledger ratify # human accept +forge ledger retract # tombstone a claim +forge ledger merge # fold a teammate's ledger in, conflict-free +forge ledger import # bridge legacy stores into the ledger +``` + +أضف `--personal` للسجل الخاص بكل مستخدم. + +## ذاكرة إعادة الاستخدام تحمل الإثبات أيضًا + +`forge reuse` هو ذاكرة تخزين مؤقت للشيفرة تحمل الإثبات. لا يُقدَّم أثر مُولَّد مرة أخرى إلا +عندما يظل دليله قائمًا — أي أن الثقة فوق الحد الأدنى **و** لا تزال تبعيات atlas الخاصة به +قابلة للحل. وإلا فإنه يسقط إلى مرحلة التوليد ويسك ادعاءً جديدًا في طريق العودة. + +```mermaid +flowchart LR + SP["spec"] --> FP["fingerprint · MinHash + LSH"] + FP --> LD["match ladder · exact to near to adapt to miss"] + LD --> GT{"confidence >= floor AND deps resolve?"} + GT -->|"yes"| SV["serve · proof holds"] + GT -->|"miss"| GN["generate"] + GN -->|"mint claim"| MT["(.forge/ledger)"] +``` + + + تطابق MinHash القريب ضعيف على المواصفات القصيرة جدًا. توفر واجهة تضمينات اختيارية + (`FORGE_EMBED`) حلًا لذلك؛ ويبقى MinHash الافتراضي الخالي من التبعيات. + diff --git a/mintlify/ar/concepts/verification-gates.mdx b/mintlify/ar/concepts/verification-gates.mdx new file mode 100644 index 0000000..b5149ac --- /dev/null +++ b/mintlify/ar/concepts/verification-gates.mdx @@ -0,0 +1,98 @@ +--- +title: "بوابات التحقق" +description: "التحقق المستقل، وعَلَم الرمز المُهلوَس، والمواصفة-كعقد، وبوابة المهارات — فحوصات يمكنك تشغيلها تُقلِّل الأخطاء لكنها لا تُشهد بالصحة أبدًا." +--- + +لا شيء يُعد "منجَزًا" دون فحص يمكنك تشغيله — اختبار، أو رمز خروج من البناء، أو لقطة شاشة. +تضيف كل من بوابات التحقق في Forge حاجزًا إضافيًا للاصطياد. مع معدل إخفاق لكل مهمة قدره +`1 − p` ومعدل اصطياد للبوابة `c`، تنخفض الإخفاقات الصامتة إلى `(1 − p)(1 − c)`، وكل بوابة +هنا هي `c` إضافية. + + + **التحقق يُقلِّل الأخطاء، ولا يُشهد بها.** مُحقِّقو الفريق (Crew) وعَلَم الرمز المُهلوَس يقلّلان + عبء المراجعة؛ لكنهما لا يثبتان صحة الشيفرة. الاختبارات والتصحيحات البشرية تفوز دائمًا. + + +## التحقق المستقل — `forge verify` + +بوابة مستقلة: تُشغّل اختبارات المستودع الحقيقية، وتضع علامة على الرموز المُهلوَسة، +وتتحقق من المصدر (provenance). + +```bash +forge verify # tests + hallucinated-symbol + provenance +forge verify --deep # multi-lens consensus — several independent checks must agree +``` + + + يُصعّد `--deep` (v0.19+) إلى إجماع متعدد العدسات: يجب أن يجتاز التغيير عدة عدسات + تحقق مستقلة، لا عدسة واحدة فقط. + + +## عَلَم الرمز المُهلوَس — `forge atlas has` + +`forge atlas has ` هو فحص الهلوسة: إذا استدعى النموذج رمزًا ليس في الرسم البياني +للشيفرة، تضع البوابة علامة عليه. + +```bash +forge atlas build # index this repo's symbols → .forge/atlas.json +forge atlas has useAuth # "not found" = likely hallucinated +``` + +الأطلس (atlas) هو JSON عادي عن قصد — يقرأ Codex وCursor وGemini وAider ملف +`.forge/atlas.json` عبر CLI أو `jq` العادي، دون أي اعتماد على MCP. + +## المواصفة-كعقد — `forge spec` + +ثبِّت السلوك في مواصفة واكتشف الانحراف عنها: + +```bash +forge spec init # scaffold an OpenSpec contract +forge spec lock # lock the current spec as the contract +forge spec check # report drift against the locked contract +``` + +## بوابة المهارات — `forge scan` + +قبل تثبيت مهارة أو خادم MCP، افحصه بحثًا عن الحقن، أو تنفيذ الشيفرة عن بُعد (RCE)، +أو تسريب البيانات: + +```bash +forge scan +``` + + + الفحص النظيف **ليس شهادة أمان.** لا تصطاد الاستدلالات المدمجة سوى أشكال الهجمات المعروفة + (الحرجة) وعدد قليل من الأنماط عالية الخطورة؛ اجتيازها يعني _"لم يُكتشف توقيع حرج"_، + وليس _"آمن للتثبيت"_. راجع دائمًا المصدر، والأذونات، ومصدر الحزمة، وسلوك الشبكة بنفسك. + النتيجة عالية الخطورة **high** لا تُوسم آمنة رغم أنها لا تحجب فعليًا. الماسح الخارجي + اختياري ولا يجري أي استدعاء شبكي إلا إذا مكّنتَه. + + +## التصليب — `forge harden` + +وصِّل ضوابط الأمان التي تُبقي الأسرار والتغييرات غير الآمنة خارج المستودع: + +```bash +forge harden # gitleaks pre-commit + sandbox settings +``` + +## بوابة على مستوى الالتزام — `forge precommit` + + + `forge precommit` (v0.19+) هي بوابة على مستوى الالتزام (commit) — تُشغّل الحد الأدنى للتحقق + وقت الالتزام حتى يُصطاد العمل الجزئي أو غير المُتحقَق منه قبل أن يهبط. + + +## فحوصات واجهة المستخدم — `forge uicheck` + +فحوصات UI حتمية، دون LLM ودون لقطات شاشة لأول ثلاث عدسات: + +```bash +forge uicheck contrast # WCAG contrast ratio +forge uicheck fingerprint # deterministic design fingerprint +forge uicheck design # slop-distance + conformance gate +forge uicheck visual # Playwright-rendered check (opt-in tier) +``` + +قرن ذلك مع `forge taste` لاختيار اتجاه بصري واحد (brutalist، corporate، +editorial، minimalist، playful) ومعايرة عتبات بوابة `design`. diff --git a/mintlify/ar/guides/radar-deps.mdx b/mintlify/ar/guides/radar-deps.mdx new file mode 100644 index 0000000..37307e4 --- /dev/null +++ b/mintlify/ar/guides/radar-deps.mdx @@ -0,0 +1,65 @@ +--- +title: "الحفاظ على تحديث التبعيات باستخدام radar" +description: "يجمع forge radar تبعياتك في حلقات حداثة (currency rings) بحيث تظهر التبعيات القديمة أو المنحرفة قبل أن تسبب مشكلات." +--- + + + `forge radar` يهبط في خط v0.19. يصف هذا الدليل كيف يتناسب مع انضباط تحديث التبعيات القائم؛ + شغّل `forge --help` للتأكد من توفره في نسختك المثبتة. + + +من قواعد الهندسة في Forge: _قبل إضافة تبعية، تحقق من الخيار الأفضل الحالي من مصادر حية، +وفضّل ما يستخدمه المشروع بالفعل._ يجعل `forge radar` الحالة القائمة لتبعياتك مرئية بحيث +تكون لهذه القاعدة بيانات تدعمها. + +## الفكرة: حلقات الحداثة + +يجمع `forge radar` تبعيات المشروع في **حلقات حداثة** متمركزة بحسب مدى حداثة كل واحدة — +من المحدَّثة في المركز إلى القديمة أو المنحرفة عند الحافة. قراءة الحلقات طريقة سريعة للإجابة +عن سؤال "ما الذي تركناه ينحرف؟" دون تدقيق كل حزمة يدويًا. + +```bash +forge radar +``` + +## من أين تأتي قائمة التبعيات + +يبني radar على قراءة البيان (manifest) نفسها التي تدعم `forge stack`، والذي يكتشف +المكدس الحقيقي للمستودع من بيانات تبعياته: + +```bash +forge stack # languages, frameworks, package managers, real test commands +``` + +ولأن الاكتشاف قائم على البيانات وآمن الفشل عبر الأنظمة البيئية (`package.json`، +`pyproject.toml`، `go.mod`، `Cargo.toml`، `Gemfile`، `composer.json`، `pom.xml` / +`build.gradle`، `*.csproj`)، يستطيع radar الاستدلال بشأن الحداثة لنفس مجموعة البيانات +التي يفهمها `stack`. + +## استخدامه في الحلقة + + + + شغّل `forge radar` لترى أي التبعيات تنحرف بالفعل قبل أن تضيف واحدة أو ترقّيها. + + + إذا كانت هناك تبعية قادرة وحديثة موجودة بالفعل في حلقة داخلية، فأعد استخدامها بدلًا + من إضافة أخرى — أصغر تغيير مناسب هو الفائز. + + + عندما ترقّي تبعية أو تستبدلها، سجّل السبب: + ```bash + forge decide "bump to — " + ``` + حتى تقرأ الجلسات المستقبلية الاختيار بدلًا من إعادة التداول فيه. + + + + + يُبلّغ radar عن الحداثة؛ لا يقوم بالترقية نيابةً عنك. عامِل حلقاته كمُدخَل استشاري لقرار + بشري — وتحقق من أي ترقية باختبارات المستودع الحقيقية (`forge verify`) قبل اعتبارها منجزة. + + + + بعد ترقية تبعية، شغّل بوابات الجودة — `forge verify` و `forge precommit`. + diff --git a/mintlify/ar/guides/team-memory.mdx b/mintlify/ar/guides/team-memory.mdx new file mode 100644 index 0000000..c225a89 --- /dev/null +++ b/mintlify/ar/guides/team-memory.mdx @@ -0,0 +1,76 @@ +--- +title: "ذاكرة الفريق باستخدام السجل" +description: "اطوِ سجل زميلك في الفريق دون تعارضات فوق git العادي — لا خادم، ولا خدمة مزامنة، فقط ملفات تتلاقى بأي ترتيب." +--- + +كل ما تتعلمه الركيزة (substrate) — دروس cortex، وحقائق `forge remember`، وآثار إعادة الاستخدام +المُتحقَّق منها — يهبط كادعاءات مُعنونة بالمحتوى في سجل أصلي لـ git (`.forge/ledger/`) مُصمَّم +ليُدمج دون تعارضات. لا خادم ولا خدمة مزامنة؛ إنها مجرد ملفات في git. + +## ذاكرة الفريق في ثلاثة أوامر + + + + ```bash + forge init + ``` + من بين أشياء أخرى، يُصدر هذا الأمر قاعدة دمج الاتحاد في `.gitattributes` التي يحتاجها السجل. + + + تُلقي دروس cortex وحقائق `forge remember` بظلال ادعاءات في السجل أثناء عملك — + لا شيء إضافي يجب تشغيله. + + + ```bash + git pull && forge ledger merge + ``` + بأي ترتيب — الدمج خالٍ من التعارضات. + + + +## لماذا لا يمكن أن يتعارض + +بايتات الادعاء هي دالة صرفة من `(kind, body, scope)`، لذا تحسب كل نسخة الهوية نفسها لنفس +المعرفة. الدمج هو شبكة نصف اتصال (join-semilattice) — مُختبَرة بخصائص تُثبت أنها تبادلية، +وتجميعية، وعديمة القوة (idempotent) — لذا تتلاقى سجلات زميلين إلى الحالة نفسها بغض النظر +عمن يزامن أولًا. + +```mermaid +flowchart LR + A["your ledger"] <-->|"git union-merge · conflict-free"| B["teammate ledger"] + A --> M["merged read view"] + B --> M + M --> R["recall list · lesson inject · brain index"] +``` + + + المعرفة المتطابقة التي تُسَك بشكل مستقل تتلاقى إلى ادعاء **واحد** مع الحفاظ على كل مؤلف + في مصدرها (provenance). + + +## الثقة والمصدر + +لا تتحرك الثقة إلا بواسطة أدوات تحقق مستقلة — اختبارات، وCI، وقبول/تراجع بشري — لذلك +فإن استيراد سجل زميل لا يثق بملاحظاته على نحوٍ أعمى؛ بل يستورد _أدلته_. + +```bash +forge ledger blame # who minted a claim, every oracle outcome, per-author trust +forge ledger stats # the merged view, by kind and trust level +forge ledger verify # confirm every claim is in normal form +``` + +## إعادة الاستخدام عبر الفريق + +بمجرد أن تكون شيفرة زميلك المُتحقَّق منها في السجل المدموج، يمكنك إعادة استخدامها مع دليلها: + +```bash +forge reuse query "" +``` + +الإصابة تشير إلى شيفرة عاملة ومؤكَّدة بالاختبارات و`forge ledger blame` التي تُثبتها — +أعد استخدامها بدلًا من إعادة توليدها. + + + تُحفظ الادعاءات الخاملة للتدقيق ولا تُحذف أبدًا؛ المعرفة غير المُراجَعة تضمحل نحو _عدم اليقين_، + لا نحو الحذف. السجل مسار أدلة، وليس ذاكرة تخزين مؤقت يمكنك أن تفقدها بصمت. + diff --git a/mintlify/ar/guides/zero-config-onboarding.mdx b/mintlify/ar/guides/zero-config-onboarding.mdx new file mode 100644 index 0000000..72f0878 --- /dev/null +++ b/mintlify/ar/guides/zero-config-onboarding.mdx @@ -0,0 +1,86 @@ +--- +title: "إعداد موجَّه بأدنى تهيئة" +description: "خمس دقائق لتصبح منتجًا: ثبِّت مرة واحدة، اضبط المستودع مرة، نفّذ مهمة، وشاهد السجل يبدأ في الإنتاجية من اليوم الثاني — موجَّه، بأدنى تهيئة، وليس بلا لمس." +--- + +يهدف Forge إلى **إعداد موجَّه بأدنى تهيئة** — عادةً ما يكون المستودع الجديد منتجًا في نحو +خمس دقائق. ثبِّت مرة واحدة، اضبط المستودع مرة، نفّذ مهمة، ثم يبدأ السجل في الإنتاجية من +اليوم الثاني. (إنه بأدنى تهيئة، وليس بلا تهيئة: لا تزال تحتاج إلى تثبيت CLI، وتشغيل +`forge init` في كل مستودع، وبعض المسارات تفترض وجود Bash وGit و`jq`.) + +```mermaid +flowchart TD + I["forge init"] --> Cfg["every tool configured from one source"] + Cfg --> Work["you work as usual"] + Work --> Gate["substrate checks each task · ask first? · which model? · what breaks?"] + Gate --> Edit["agent edits, with guardrails"] + Edit --> Learn["cortex learns from corrections"] + Learn -.->|next task is smarter| Work +``` + +## 1. التثبيت (مرة واحدة) + +المسارات الموصى بها لا تحتاج إلى رمز مصادقة ولا إلى استنساخ: + + + +```bash Plugin +/plugin marketplace add CodeWithJuber/forgekit +/plugin install forgekit +``` + +```bash CLI +npm install -g @codewithjuber/forgekit +``` + + + +```bash +forge doctor # everything green? +``` + +## 2. اضبط مستودعًا (مرة واحدة لكل مستودع) + +```bash +cd ~/your-project +forge init # emits AGENTS.md, CLAUDE.md, .gemini/settings.json, .aider.conf.yml … +``` + +الآن يقرأ Claude Code وCodex وCursor وGemini وAider وCopilot وWindsurf وZed وContinue +**نفس** القواعد — كل واحد منها من ملفه الأصلي. غيّر قاعدة لاحقًا بتحرير `source/rules.json` +(أو بإفلات `.forge/rules.json` خاص بالمستودع)، ثم شغّل `forge sync`. + +## 3. استخدم الركيزة الإدراكية + +```bash +forge substrate "" # ask/route/impact/scope/reuse/context/memory/verify in one pass +forge substrate "" --json +forge impact # the blast radius on its own +``` + +إذا قال `forge substrate` `ASK FIRST`، فاسأل الأسئلة الواردة قبل التعديل. + +## 4. استخدم الإضافات + +```bash +forge atlas build # index this repo's symbols → .forge/atlas.json +forge atlas query useAuth # where is it defined? +forge atlas has useAuth # does it exist? "not found" = likely hallucinated +forge recall add "db port" "Postgres is on 5433 here, not 5432" +forge catalog # the Start-Here index of everything +``` + +## 5. اليوم الثاني: السجل يتعلم + +كل ما تعلمته الركيزة في اليوم الأول — دروس cortex، والحقائق المتذكَّرة، والشيفرة المُتحقَّق منها — +هبط كادعاءات في `.forge/ledger/`. + +```bash +forge ledger stats # what the repo knows, by kind and trust level +forge ledger blame # who minted a claim, every oracle outcome +forge reuse query "" # verified code you already have +``` + + + التالي: اطوِ سجل زميلك في الفريق دون تعارضات فوق git العادي. + diff --git a/mintlify/ar/installation.mdx b/mintlify/ar/installation.mdx new file mode 100644 index 0000000..5376b15 --- /dev/null +++ b/mintlify/ar/installation.mdx @@ -0,0 +1,106 @@ +--- +title: "التثبيت" +description: "ثلاثة أبواب أمامية لشجرة واحدة: سوق الإضافات، وتثبيت npm العام، وتثبيت github: دون سجل — إضافةً إلى إعداد المساهمين بالروابط الرمزية." +--- + +يتّبع Forge تصميم **شجرة واحدة وثلاثة أبواب أمامية**: بيان المُلحق، والمُثبِّت المُقوّى، +وثنائي npm العام، جميعها تشير إلى الشجرة نفسها `global/` + `source/`. اختر القناة +الملائمة لأداتك. + +## اختر قناة + + + + لأداتَي Claude Code وCodex. تُوصَل الحواجز تلقائيًا؛ لا شيء يُدمج. + + + لأي أداة. واجهة سطر أوامر `forge` من سجل npm العام. + + + لا حاجة إلى سجل — ثبّت مباشرة من المستودع. + + + استنساخ + `npm link`، أو `bash install.sh` لإعداد الروابط الرمزية. + + + +## المتطلبات + +- **Node.js >= 20** +- **صفر تبعيات وقت التشغيل** — كل شيء مبني داخل Node. الطبقات الاختيارية + (تضمينات `FORGE_EMBED`، وPlaywright لأمر `uicheck visual`) اختيارية ولا تضيف أي + تبعيات مطلوبة. + +## سوق المُلحقات + +المسار الموصى به لأداتَي Claude Code وCodex لا يحتاج رمزًا ولا استنساخًا: + +```bash +/plugin marketplace add CodeWithJuber/forgekit +/plugin install forgekit +``` + +يوصل المُلحق الحواجز عبر `${CLAUDE_PROJECT_DIR}` بحيث تعمل بوّابتا ما قبل الفعل والإكمال +بشكل ضمني. + +## npm العام + +لأي أداة، من npm العام: + +```bash +npm install -g @codewithjuber/forgekit +forge doctor # everything green? +``` + +## تثبيت github: دون سجل + +```bash +npm install -g github:CodeWithJuber/forgekit +``` + +## مساهم / تطوير محلي + + + +```bash npm link +git clone https://github.com/CodeWithJuber/forgekit.git +cd forgekit +npm link +``` + +```bash install.sh (symlink setup) +git clone https://github.com/CodeWithJuber/forgekit.git +cd forgekit +bash install.sh +``` + + + +المُثبِّت مُقوّى: عديم الأثر، ومبني على الروابط الرمزية، مع نسخة احتياطية، ودون +`curl | sh`. + +## التحقّق + +مهما كانت القناة التي استعملتها، تأكّد من التثبيت: + +```bash +forge doctor # tools, guards, MCP auth, config drift, update status +``` + + + يُظهر `forge doctor` أيضًا إشعارًا غير مُلحّ بشأن "التزامات متأخرة عن المنبع" لعمليات + استنساخ git. اضبط `FORGE_NO_UPDATE_CHECK=1` لإسكاته. كل مسار يفشل بلطف — دون + اتصال أو رأس منفصل يُبلَّغ عن "غير معروف"، لا خطأ. + + +## إبقاء Forge محدَّثًا + +```bash +forge update --check # report whether a newer version is available +forge update # apply the update (git checkout or npm/copy install) +forge update --to # pin or downgrade to a specific version +``` + + + انتقل إلى البدء السريع لتشغيل `forge init` وأول فحص للركيزة. + diff --git a/mintlify/ar/introduction.mdx b/mintlify/ar/introduction.mdx new file mode 100644 index 0000000..d3a2f14 --- /dev/null +++ b/mintlify/ar/introduction.mdx @@ -0,0 +1,130 @@ +--- +title: "مقدمة" +description: "Forge هو الركيزة المعرفية التي يفتقدها كل نموذج عديم الحالة — الذاكرة، والاستشراف، وحواجز الأمان — يُقدَّم كإعداد أصلي لكل وكيل برمجة يعتمد على الذكاء الاصطناعي." +--- + +**دماغ واحد لكل وكيل برمجة يعتمد على الذكاء الاصطناعي.** النموذج اللغوي الكبير عديم +الحالة: نافذة سياق واحدة، تُمسح مع كل استدعاء. ليس لديه أي ذاكرة بما تعلمه فريقك، ولا +استشراف لما قد يكسره أي تعديل، ولا حواجز أمان مُنفَّذة. إن Forge +(`@codewithjuber/forgekit`) هو **الركيزة المعرفية** — الطبقة التي تعمل +_قبل_ أن يعدّل النموذج الشيفرة، والتي تُوفّر ذاكرةً مرجعية للأدلة وعنوانها محتواها (نُطلق +عليها اسم "الذاكرة الحاملة للإثبات")، واستشرافًا استدلاليًا للأثر، وحواجز أمان مُنفَّذة — +وكذلك **مُصرِّف إعدادات عابر للأدوات** يوصل هذا الدماغ كإعداد أصلي إلى كل الأدوات +دفعة واحدة. أعمق تكامل مُختبَر هو مع Claude Code؛ أما البقية فتحصل على إعداد أصلي +وأدوات MCP، مع تجربة ميدانية أقل. + + + + ذاكرة حاملة للإثبات تدوم عبر الجلسات وبين أعضاء الفريق. كل درس، وحقيقة، وإعادة استخدام + مُتحقَّق منها هي ادعاء يحمل دليله معه. + + + نصف قطر الانفجار لأي تعديل — مجموعة الملفات المتوقع أن يمسّها، مقروءةً من رسم + الشيفرة، بما في ذلك الملفات المُترابطة التي لم تسمّها. + + + خطّافات حتمية تُنفّذ القواعد التي لا يجوز للنموذج أن يخالفها أبدًا. تصمد بعد ضغط + السياق بطريقة لا يصمد بها النص الطليق في ملف إعدادات. + + + +## المشكلة + +النموذج اللغوي الكبير عديم الحالة — نافذة سياق واحدة، تُمسح مع كل استدعاء. + +- **لا يملك أي ذاكرة** بما تعلمه فريقك سابقًا. +- **لا يملك أي استشراف** لما سيكسره أي تعديل. +- **لا يملك أي حواجز أمان مُنفَّذة** — القواعد النصية تُنسى بعد الضغط. + +وكل أداة تريد ملف إعدادات خاصًا بها (`CLAUDE.md`، `AGENTS.md`، `.cursor/rules`، +`GEMINI.md`، MCP…). إن Forge هو الركيزة المعرفية التي تُوفّر الأشياء الثلاثة المفقودة، +والمُصرِّف الذي يوصلها إلى كل أداة من مصدر واحد. + +## الأطروحة + +لا يستطيع النموذج أن يتعلم من قاعدة شيفرتك بين الاستدعاءات: أوزانه مُجمَّدة وذاكرته +العاملة تُمسح بعد كل استجابة. لا يمكن حَقن الذاكرة والاستشراف والتحقق الذاتي فيه عبر +الطلبات — يجب توفيرها من _الخارج_. تلك الطبقة الخارجية هي الركيزة المعرفية. رياضيًا، +الاستدلال هو دالة ثابتة `y = f(x)` بلا حالة بين الاستدعاءات؛ وForge هو الحالة. + + + + اكتب قواعدك وإعدادات الركيزة الافتراضية في مصدر واحد قانوني + (`source/rules.json`، `source/substrate.json`، `source/mcp.json`). + + + يقوم `forge sync` بتصريف هذا المصدر إلى الإعداد الأصلي لكل أداة — تسع أدوات برمجة + مدعومة بالذكاء الاصطناعي إضافةً إلى MCP — مع ترويسة تجزئة للمحتوى، فيصير الانحراف + قابلًا للكشف وإعادة التشغيل بلا أثر. + + + يُشغّل `forge substrate ""` تمريرًا حتميًا واحدًا قبل الفعل: الافتراضات، + والتوجيه، وإعادة الاستخدام، والسياق، ونصف قطر الانفجار، والنطاق، ومرساة الهدف. + + + فقط الأدوات المستقلة — الاختبارات وCI وقبول/تراجع الإنسان — هي التي تحرّك ثقة + الذاكرة، بحيث يتلاشى الدرس الخاطئ بدلًا من أن يتحجّر. + + + +## ماذا تحصل + +- **ذاكرة تدوم عبر الجلسات وبين أعضاء الفريق.** كل درس، وحقيقة، وإعادة استخدام + مُتحقَّق منها هي _ذاكرة حاملة للإثبات (PCM)_ — اسمنا للذاكرة المرجعية للأدلة والمعنونة + بمحتواها: ادعاء يحمل مراجع لأدلته ولا يُوثَق به إلا عندما ترفع الأدوات المستقلة ثقته + فوق حدٍّ أدنى. "الإثبات" هو مسار الأدلة، لا برهان صوري. +- **استشراف قبل أن تكسر الأشياء.** اسأل "ماذا يكسر تغييرُ `verifyToken`؟" + واحصل على نصف قطر الانفجار من رسم الشيفرة، بما في ذلك الملفات المترابطة التي لم تسمّها. +- **حواجز أمان لا يمكن نسيانها.** خطّافات حتمية تُنفّذ المسارات المحمية، + وميزانيات التكلفة، وكشف الحلقات الهالكة — وتصمد بعد ضغط السياق. +- **عمل يكتمل من طرف إلى طرف.** بوّابة إكمال تحجب "تم" مرة واحدة في كل جلسة + عند تحرّك الشيفرة دون أن يتبعها توثيق أو أثر حالة، مع قائمة الإصلاح كإجابة. +- **إعداد واحد لتسع أدوات.** اكتب قواعدك مرة واحدة؛ يُصدر Forge الإعداد الأصلي + لكل أداة، إضافةً إلى MCP لأدوات Roo وVS Code. صفر تبعيات وقت التشغيل — CLI واحد + بلغة Node، وملفات عادية في git، دون خادم. + +## أي أدوات يُغذّي Forge؟ + +يُصدر Forge إعدادات لـ **تسع أدوات**، إضافةً إلى خادم MCP لأداتَي Roo Code وVS Code: +Claude Code، وCodex، وCursor، وGemini، وAider، وCopilot، وWindsurf/Devin، وZed، +وContinue. تقرأ كلٌّ منها القواعد نفسها من ملفها الأصلي. + +## الحدود الصادقة + +يُعلن Forge سقفه في كل مكان. + + + إن Forge **يُقلّل ولا يُلغي** انحراف القواعد. هو طبقة شفافية وموثوقية، + لا بديل للاختبارات أو المراجعة أو الحكم البشري. + + +- **الحواجز تُنفّذ فقط ما يمكن التعبير عنه كخطّاف** (المسارات، والتنسيق، وحجم الفرق، + والميزانية). القواعد الدلالية ("فضّل الأسلوب الدالّي") تبقى نصًا وقد تُتجاهل أحيانًا. +- **التحقق يُقلّل ولا يشهد.** يُقلّص الفريق المُتحقِّق وعَلَم الرموز المُهلوَسة عبء + المراجعة؛ لكنها لا تُثبت صحة الشيفرة. +- **لا تعلّم على مستوى الأوزان.** `recall` / `cortex` ذاكرة ملفات وطلبات فقط — + لا تعلّم مُعزَّز ولا ضبط دقيق. +- **رسم الأثر تقريبي بواسطة regex** — متحفّظ لا رسم استدعاء دقيق. +- **الاختبارات وتصحيحات الإنسان تفوز دائمًا.** + + + إن Forge في مرحلة **بيتا**. النواة (`init`، `sync`، `substrate`، `impact`، `ledger`، + والحواجز) مُختبَرة ومستخدمة يوميًا؛ قد تتغيّر بعض العلامات قبل `1.0`. + + +## الخطوات التالية + + + + ثبِّت، وشغّل `forge init`، ومرِّر مهمتك الأولى عبر الركيزة. + + + المُصرِّف رباعي الطبقات، والذاكرة الحاملة للإثبات، وبوّابة ما قبل الفعل. + + + كل أمر مُصنَّف حسب المجموعات: Core وMemory وSubstrate وQuality وConfig. + + + ادمج سجل زميلك في فريقك بلا تعارضات، عبر git عادي. + + diff --git a/mintlify/ar/quickstart.mdx b/mintlify/ar/quickstart.mdx new file mode 100644 index 0000000..7790b69 --- /dev/null +++ b/mintlify/ar/quickstart.mdx @@ -0,0 +1,107 @@ +--- +title: "البدء السريع" +description: "ثبّت Forge، وأصدر إعداد كل أداة من مصدر واحد، وشغّل أول بوّابة قبل الفعل — في نحو 60 ثانية." +--- + +انتقل من الصفر إلى مستودع مُعدّ وأول فحص للركيزة في حوالي دقيقة. + +## 1. التثبيت + + + +```bash Plugin (Claude Code / Codex) +/plugin marketplace add CodeWithJuber/forgekit +/plugin install forgekit +``` + +```bash npm (any tool) +npm install -g @codewithjuber/forgekit +``` + +```bash No registry +npm install -g github:CodeWithJuber/forgekit +``` + + + +المسار عبر المُلحق هو الموصى به لأداتَي Claude Code وCodex — تُوصَل الحواجز تلقائيًا +ولا يوجد ما يُدمج. راجع [التثبيت](/ar/installation) للمصفوفة الكاملة، بما في ذلك إعداد +التطوير بالروابط الرمزية. + +## 2. إعداد المستودع + + + + ```bash + cd ~/your-project + forge init + ``` + يُصدر هذا `AGENTS.md`، و`CLAUDE.md`، و`.gemini/settings.json`، و`.aider.conf.yml`، + والباقي — إضافةً إلى قاعدة الدمج الاتحادي في `.gitattributes` التي يحتاجها السجل. + الآن تقرأ Claude Code، وCodex، وCursor، وGemini، وAider، وCopilot، وWindsurf، وZed، + وContinue **القواعدَ نفسها**، كلٌّ من ملفها الأصلي. + + + ```bash + forge doctor + ``` + فحص نجاح/إخفاق للأدوات المثبتة، والحواجز، ومصادقة MCP، وانحراف الإعدادات. + + + عدّل `source/rules.json` (أو ضع `.forge/rules.json` خاصًا بالمستودع)، ثم أعد التصريف: + ```bash + forge sync + ``` + الأمر `sync` عديم الأثر — يعيد كتابة ما تغيّر فقط. + + + +## 3. تشغيل بوّابة ما قبل الفعل + +الركيزة هي الطبقة التي تعمل _قبل_ أن يعدّل النموذج الشيفرة. أمر واحد يُشغّل البوّابة +بأكملها: + +```bash +forge substrate "Change verifyToken in src/auth.js to require length > 20; update tests" +# → assumption verdict · cheapest capable model · predicted blast radius +# (including files you didn't name) · scope clusters · verification checklist +``` + + + في Claude Code تعمل الركيزة تلقائيًا **على كل طلب** عبر خطّاف + `UserPromptSubmit` — إرشادية فقط، وصامتة عند المهام النظيفة. تحصل كل أداة أخرى على + قاعدة إعداد أصلية إضافةً إلى 19 أداة MCP يمكنها استدعاؤها بنفسها. + + +إذا قال `forge substrate` `ASK FIRST`، اسأل الأسئلة المُرجَعة قبل التعديل. اقرأ الملفات +المتوقع تأثرها — نصف قطر الانفجار — قبل أي تغيير مُعدِّل. + +```bash +forge substrate "" --json # machine-readable verdict +forge impact # the blast radius on its own +``` + +## 4. استكشف الإضافات + +```bash +forge atlas build # index this repo's symbols → .forge/atlas.json +forge atlas query useAuth # where is it defined? (cheaper than grep-and-read) +forge atlas has useAuth # does it exist? "not found" = likely hallucinated +forge recall add "db port" "Postgres is on 5433 here, not 5432" +forge catalog # the Start-Here index of everything +``` + +## 5. اليوم الثاني: السجل يتعلّم + +كل ما تعلمته الركيزة في اليوم الأول أُودع كادعاءات في `.forge/ledger/`. هذه هي +الذاكرة الحاملة للإثبات — والآن يبدأ عائدها: + +```bash +forge ledger stats # what the repo knows, by kind and trust +forge ledger blame # who minted a claim, every oracle outcome +forge reuse query "" # verified code you already have +``` + + + اقرأ كيف تُركّب بوّابة ما قبل الفعل مراحلها في حكم واحد. + diff --git a/mintlify/cn/cli/config.mdx b/mintlify/cn/cli/config.mdx new file mode 100644 index 0000000..cc7e419 --- /dev/null +++ b/mintlify/cn/cli/config.mdx @@ -0,0 +1,91 @@ +--- +title: "Config 命令" +description: "提供方、成本、仪表盘、品牌、atlas 和技术栈：config、cost、dash、brand、atlas、stack —— 外加 v0.19+ 的 report 和 tools 命令。" +--- + +Config 分组涵盖提供方、可观测性、代码图和技术栈探测。 + +## `forge config` + +提供方配置 —— 显示 / 切换 / 添加提供方，设置默认模型。 + +```bash +forge config # show current config +forge config switch +forge config add +``` + +## `forge cost` + +通过实测的阶段系数得到真实的每日开销。 + +```bash +forge cost # real per-day spend +forge cost --stages # measured per-stage cost factors +``` + + + 只报告**实测的阶段** —— 一个没有事件记录的阶段会显示"no data"，绝不会给出 + 一个默认值。 + + +## `forge dash` + +跑在账本、指标和爆炸半径之上的本地仪表盘。 + +```bash +forge dash # localhost-only, read-only (default port 4242) +``` + +## `forge brand` + +打印当前的品牌 token 映射。 + +```bash +forge brand +``` + +品牌以一份 token 存储在（`brand.json`）里；换品牌就是一次编辑。 + +## `forge atlas` + +构建 / 查询代码图。 + +```bash +forge atlas build [path] # walk the tree → .forge/atlas.json +forge atlas query "what calls Z" +forge atlas has # hallucinated-symbol check +``` + +atlas 是纯 JSON —— 任何工具都能读，不需要 MCP。 + +## `forge stack` + +从本仓库的清单文件里探测它真实的技术栈。 + +```bash +forge stack +``` + +会读取 `package.json`、`pyproject.toml`、`go.mod`、`Cargo.toml`、`Gemfile`、 +`composer.json`、`pom.xml` / `build.gradle` 以及 `*.csproj`，报告语言、 +框架、包管理器和仓库**真正**的测试命令 —— 这些会喂给 +基底的验证清单。 + +## `forge report` v0.19+ + +生成本仓库 Forge 状态的静态 HTML 报告 —— 把账本、指标和爆炸 +半径渲染成一个可以分享或归档的、自包含的文件。 + +```bash +forge report +``` + +## `forge tools` v0.19+ + +选择本仓库的主 AI 编码工具，并接通对应的 `.gitignore` 条目，让 +生成的配置和 `.forge/` 产物在你的这套配置里被正确忽略。 + +```bash +forge tools +``` diff --git a/mintlify/cn/cli/core.mdx b/mintlify/cn/cli/core.mdx new file mode 100644 index 0000000..68e14fc --- /dev/null +++ b/mintlify/cn/cli/core.mdx @@ -0,0 +1,76 @@ +--- +title: "Core 命令" +description: "引导并维护一个仓库：init、sync、doctor、catalog、docs 和 update。" +--- + +Core 分组用于引导一个仓库并保持它的健康。 + +## `forge init` + +搭起本仓库的配置 —— 从同一份共享来源为每个工具输出配置。 + +```bash +forge init +``` + +输出 `AGENTS.md`、`CLAUDE.md`、`.gemini/settings.json`、`.aider.conf.yml` 等文件 +（外加给 Roo Code 和 VS Code 的 MCP 服务器配置），以及账本所需的 +`.gitattributes` union-merge 规则。 + +## `forge sync` + +把规范来源重新编译成每个工具的原生配置文件。 + +```bash +forge sync +``` + +幂等 —— 只重写发生变化的部分。在编辑 `source/rules.json` 或 +仓库级的 `.forge/rules.json` 之后运行它。 + +## `forge doctor` + +对已安装工具、护栏、MCP 认证和配置漂移做健康检查。 + +```bash +forge doctor +``` + +对工具、护栏、MCP 接线、配置漂移和更新状态做通过/失败检查。所有路径 +都是 fail-open。当配置了自定义网关时，**gateway models** 一行会打印 +出解析后的 `tier → model` 映射。 + +## `forge catalog` + +Start Here —— 列出每个工具、crew 和护栏，附上一行原因。 + +```bash +forge catalog +``` + +## `forge docs` + +文档 ↔ 代码漂移。 + +```bash +forge docs check # registry reconcile — commands, env vars, MCP tools, CHANGELOG +forge docs sync # diff-driven stale-docs sweep +``` + + + 当命令、环境变量、MCP 工具或 CHANGELOG 相对代码发生漂移时，`docs check` 会让 CI + 失败。`docs sync` 扫描 diff，并报告 UPDATED / STALE / VERIFIED-UNAFFECTED。 + + +## `forge update` + +跨三种安装方式的自更新。 + +```bash +forge update # apply the update (git checkout or npm/copy install) +forge update --check # report whether a newer version is available +forge update --to # pin or downgrade to a specific version (v0.19+) +``` + +所有路径都是 fail-open —— 离线、无上游或 detached HEAD 都会返回"unknown"， +永远不会报错。`FORGE_NO_UPDATE_CHECK=1` 让 doctor 的提示安静下来。 diff --git a/mintlify/cn/cli/memory.mdx b/mintlify/cn/cli/memory.mdx new file mode 100644 index 0000000..88967c9 --- /dev/null +++ b/mintlify/cn/cli/memory.mdx @@ -0,0 +1,107 @@ +--- +title: "Memory 命令" +description: "跨会话与团队记忆：cortex、recall、remember、brain、ledger、reuse、handoff 和 decide —— 全部汇聚到那本携带证据的账本。" +--- + +Memory 分组管理跨会话与团队记忆。所有内容都汇聚到 `.forge/ledger/` 下 +那本携带证据的账本。模型细节见 +[Proof-carrying memory](/cn/concepts/proof-carrying-memory)。 + +## `forge cortex` + +自我纠正的项目记忆 —— 从修正中挖掘出来的经验。 + +```bash +forge cortex status # what's been learned +forge cortex why # why a lesson applies here +``` + +## `forge recall` + +管理跨会话的个人记忆。 + +```bash +forge recall list # facts the recall-load guard injects next session +forge recall add "db port" "Postgres is on 5433 here, not 5432" +forge recall consolidate # summarize (advisory, human-reviewable) +``` + +## `forge remember` + +给本仓库的可移植记忆添加一条持久的、可提交进 git 的事实。 + +```bash +forge remember "" +``` + +## `forge brain` + +展示或重建可移植的项目记忆索引。 + +```bash +forge brain # show the index +forge brain --rebuild # rebuild it +``` + +## `forge ledger` + +携带证据的记忆 —— 按内容寻址的声明存储。 + +```bash +forge ledger stats # what the repo knows, by kind and trust level +forge ledger verify # re-check claims are in normal form +forge ledger show # a claim and its evidence +forge ledger blame # who minted it, every oracle outcome, per-author trust +forge ledger query "" # retrieve by relevance +forge ledger ratify # human accept +forge ledger retract # tombstone a claim +forge ledger merge # fold a teammate's ledger in, conflict-free +forge ledger import # bridge legacy stores into the ledger +``` + +加 `--personal` 是每用户的账本。 + +## `forge reuse` + +携带证据的代码缓存 —— 只有当证据依然成立时才会命中。 + +```bash +forge reuse query "" # verified code you already have +forge reuse mint "" --file # add an artifact to the cache +forge reuse stats # cache stats +``` + +## `forge handoff` + +有界的会话快照 —— 重写 `.forge/state.md`，每次会话开始时会重新注入。 + +```bash +forge handoff "" --next "" +``` + +## `forge decide` + +只追加的决策日志 —— 在 `.forge/decisions.md` 里的 `D-####` ADR-lite 条目。 + +```bash +forge decide " — " +forge decide # read the log before re-deciding +``` + +## `forge know` v0.19+ + +把一条事实路由到它正确的存储归宿 —— 决定一条知识应该落在 +`recall`、`remember`/`brain`、决策还是 cortex 经验里，并把它归档到那里。 + +```bash +forge know "" +``` + +## `forge deja` v0.19+ + +相似历史工作查找 —— 从账本中找出与你即将要做的事情 +相似的旧工作，让你复用已有的证据，而不是重新生成。 + +```bash +forge deja "" +``` diff --git a/mintlify/cn/cli/overview.mdx b/mintlify/cn/cli/overview.mdx new file mode 100644 index 0000000..733bd81 --- /dev/null +++ b/mintlify/cn/cli/overview.mdx @@ -0,0 +1,61 @@ +--- +title: "CLI 概览" +description: "每个 forge 命令，按 Core、Memory、Substrate、Quality 和 Config 分组 —— 命令表本身就是数据，会被严格的漂移检查对着文档核对。" +--- + +`forge` 命令表以数据形式定义在 `src/commands.js` 里，并由 `forge docs check` +对着文档核对，所以一个命令没法在文档没注意到的情况下就上线或消失。命令按五组 +组织。 + + + + 引导和维护：`init`、`sync`、`doctor`、`catalog`、`docs`、`update`。 + + + 跨会话与团队记忆：`cortex`、`recall`、`remember`、`brain`、`ledger`、 + `reuse`、`handoff`、`decide`。 + + + 动作前门及其各个阶段：`substrate`、`preflight`、`route`、`impact`、 + `scope`、`context`、`anchor`、`diagnose`、`imagine`、`lean`。 + + + 验证与安全：`verify`、`scan`、`spec`、`taste`、`uicheck`、`harden`。 + + + 提供方、成本、仪表盘、品牌、atlas、技术栈：`config`、`cost`、`dash`、`brand`、 + `atlas`、`stack`。 + + + +## 约定 + +- **默认建议性。** 设置 `FORGE_ENFORCE=1` 就能让基底在最强信号上变成硬阻塞 + （空洞的提示、无法拼齐的必需上下文、超出默认 25 文件阈值的爆炸 + 半径）。 +- **默认安静。** 每条命令的 `Forge — …` 标题只是品牌装饰，藏在 + `--verbose` / `FORGE_VERBOSE` 后面；命令会先输出它的结果。 +- **管道友好。** 被管道时输出纯文本；在 TTY 上会加上品牌配色和 + 置信度条。`NO_COLOR` 关闭颜色，`FORCE_COLOR=1` 强制打开。 +- **`--json`** 在基底和大多数分析类命令上都可用，方便脚本化。 + + + 运行 `forge --help` 得到永远最新的命令列表，或 `forge catalog` 得到 + 一份"Start Here"索引，列出每个工具、crew 和护栏，附上一行简介。 + + +## v0.19+ 新增 + +有几条命令和标志正在 v0.19 线路上落地。它们在各自的分组页里都有 +文档，并会在行内标注： + +| 命令 / 标志 | 分组 | 作用 | +| ---------------------- | -------- | ------------------------------------------------ | +| `forge know` | Memory | 把一条事实路由到它正确的存储归宿。 | +| `forge deja` | Memory | 相似历史工作查找。 | +| `forge precommit` | Quality | 提交级验证门。 | +| `forge radar` | Quality | 依赖新鲜度环。 | +| `forge report` | Config | 仓库 Forge 状态的静态 HTML 报告。 | +| `forge tools` | Config | 主工具选择 + gitignore 接线。 | +| `forge verify --deep` | Quality | 多视角共识验证。 | +| `forge update --to` | Core | 固定或降级到某个具体版本。 | diff --git a/mintlify/cn/cli/quality.mdx b/mintlify/cn/cli/quality.mdx new file mode 100644 index 0000000..b8e830c --- /dev/null +++ b/mintlify/cn/cli/quality.mdx @@ -0,0 +1,84 @@ +--- +title: "Quality 命令" +description: "验证与安全：verify、scan、spec、taste、uicheck 和 harden —— 外加 v0.19+ 的 precommit 和 radar 门。" +--- + +Quality 分组是验证和安全面。它们如何组合，见 +[验证门](/cn/concepts/verification-gates)。 + +## `forge verify` + +独立验证门 —— 测试 + 幻觉符号 + 出处溯源。 + +```bash +forge verify +forge verify --deep # multi-lens consensus (v0.19+) +``` + +## `forge scan` + +技能门 —— 在安装前审核一个 skill 或 MCP 服务器是否有注入 / RCE / 数据外泄风险。 + +```bash +forge scan +``` + +## `forge spec` + +规范即契约 —— 初始化（OpenSpec）、锁定，并检查漂移。 + +```bash +forge spec init +forge spec lock +forge spec check +``` + +## `forge taste` + +为本仓库启用一个 UI-taste 工具（不带参数会列出可选项）。 + +```bash +forge taste # list the profiles +forge taste # brutalist · corporate · editorial · minimalist · playful +``` + +会写出 `DESIGN.md` 并对 `uicheck design` 门的阈值做参数化。 + +## `forge uicheck` + +确定性的 UI 检查。 + +```bash +forge uicheck contrast # WCAG contrast ratio +forge uicheck fingerprint # deterministic design fingerprint +forge uicheck design # slop-distance + conformance gate +forge uicheck visual # Playwright-rendered check (opt-in tier) +``` + +## `forge harden` + +接通安全控制 —— gitleaks pre-commit + 沙盒设置。 + +```bash +forge harden +``` + +## `forge precommit` v0.19+ + +提交级门 —— 在提交时跑一遍验证底线，让部分完成或未验证的 +工作在落地之前就被拦住。 + +```bash +forge precommit +``` + +## `forge radar` v0.19+ + +依赖新鲜度环 —— 按项目依赖的新鲜程度分组，让陈旧或漂移中的依赖 +在咬人之前先浮出水面。 + +```bash +forge radar +``` + +如何读这些环，见 [保持依赖新鲜](/cn/guides/radar-deps) 指南。 diff --git a/mintlify/cn/cli/substrate.mdx b/mintlify/cn/cli/substrate.mdx new file mode 100644 index 0000000..78cb06c --- /dev/null +++ b/mintlify/cn/cli/substrate.mdx @@ -0,0 +1,103 @@ +--- +title: "Substrate 命令" +description: "动作前门以及可以单独调用的各个阶段：substrate、preflight、route、impact、scope、context、anchor、diagnose、imagine 和 lean。" +--- + +Substrate 分组就是动作前门。`forge substrate` 把其他阶段组合成一个统一的 +裁决；每个阶段也可以单独调用。管线细节见 +[动作前门](/cn/concepts/pre-action-gate)。 + +## `forge substrate` + +一个动作前门：assumptions、route、impact、scope、memory、verify。 + +```bash +forge substrate "" +forge substrate "" --json +``` + +如果它返回 `okToProceed:false`，在编辑前先问它返回的 `assumption.questions`。 + +## `forge preflight` + +假设检查 —— 找出任务里点名了但仓库并未定义的东西。 + +```bash +forge preflight "" +``` + +## `forge route` + +为一个任务推荐最便宜的能胜任的模型。 + +```bash +forge route "" +forge route gateway # emit LiteLLM gateway config +``` + +## `forge impact` + +从 atlas 图中预测某个符号或文件的爆炸半径。 + +```bash +forge impact +``` + +## `forge scope` + +把文件拆解成独立的簇 —— 外加你没点名的耦合文件。 + +```bash +forge scope +``` + +## `forge context` + +有预算的上下文拼装 + 完备性门 —— 一次编辑必须知道的东西。 + +```bash +forge context "" +``` + +在预测的编辑集合上用集合覆盖法拼装出一个受预算约束的上下文，套一层 +压缩阶梯，并报告算出来的缺失集合。 + +## `forge anchor` + +目标漂移检查 —— 你实际的（git）改动是不是还在既定目标上？ + +```bash +forge anchor set "" # persist the goal across sessions +forge anchor show +forge anchor clear +``` + +## `forge diagnose` + +死循环检查 —— 记录一次失败；同样特征连续出现 3 次会生出一条诊断 + 上报。 + +```bash +forge diagnose "" +``` + +## `forge imagine` + +后果模拟 —— 针对某个任务给出预测的破坏点 + 最小的干跑测试套件。 + +```bash +forge imagine "" +forge imagine "" --run # execute the minimal suite sandboxed +``` + +## `forge lean` + +范围最小性 (M5) —— 衡量 diff 的足迹相对任务所要求的大小。 + +```bash +forge lean +``` + + + `route`、`impact`、`scope`、`context`、`anchor` 和 `lean` 各阶段都在 + `forge substrate` 里跑。当你只需要某一个信号时才单独调用它们。 + diff --git a/mintlify/cn/concepts/config-compiler.mdx b/mintlify/cn/concepts/config-compiler.mdx new file mode 100644 index 0000000..9f49274 --- /dev/null +++ b/mintlify/cn/concepts/config-compiler.mdx @@ -0,0 +1,100 @@ +--- +title: "四层配置编译器" +description: "只写一次基底；forge sync 会把它编译成每个工具的原生配置。四层描述的是这个大脑如何被表达，编译器描述的是它如何被交付。" +--- + +你只写一次基底。`forge sync` 会把这份来源编译成每个工具的原生 +配置。四层描述的是 _大脑如何被表达_；编译器描述的是它 _如何被 +交付_。 + +```mermaid +flowchart TD + S["source/ · rules.json · substrate.json · mcp.json"] -->|"forge sync — content-hash + DO-NOT-EDIT headers"| N["native configs · CLAUDE.md · AGENTS.md · .cursor · .gemini · .aider"] + S -. configures .-> L + subgraph L["the four layers"] + direction LR + T["tools · model-invoked skills"] + C["crew · isolated sub-agents"] + G["guards · deterministic hooks"] + M["mcp · atlas + substrate server"] + end +``` + +## 一份来源，多个输出 + +规则只写**一次**（`source/rules.json`）；一个确定性的编译器（`forge sync`） +把它输出成每个工具的原生格式，带一个内容哈希头，所以漂移是可探测的， +再跑一次是幂等的。任何一条规则都不会被写两遍。规范来源由三个 +文件组成： + +| 来源文件 | 存放什么 | +| ----------------------- | -------------------------------------------------------------------- | +| `source/rules.json` | 规范的工程规则（git、测试、安全、风格）。 | +| `source/substrate.json` | 认知基底默认值 —— 阈值、路由、LLM 的调节参数。 | +| `source/mcp.json` | 输出到每个工具的 MCP 服务器定义。 | + +## 四层 + +每一层都有品牌名，并且跨工具输出。 + + + + `~/.forge/tools/` → `~/.claude/skills/`。模型可调用的 skill，遵循 + `SKILL.md` 标准（frontmatter 里的 `name` + `description`）。 + + + `~/.forge/crew/` → `~/.claude/agents/`。上下文隔离的子代理，例如 scout、 + verifier 和 frontend-verifier。 + + + `~/.forge/guards/` → `settings.json` hooks。**唯一进行 _强制_ 而不只是 + _建议_ 的层。** 一个 guard 就是一个确定性钩子，模型没法漂离它。 + `CLAUDE.md` 里的自然语言规则会被口头承认，然后在压缩之后被遗忘；一个 guard + 不会。每一条可强制的不变量都应该落在这里。 + + + Forge 内置一个 stdio 服务器（`src/cortex_mcp.js`），暴露 19 个 MCP 工具： + 基底检查（`substrate_check` / `predict_impact` / `assumption_gate` / …）、 + 记忆的读 _和_ 写（`forge_remember`、账本的 ratify/retract），以及运维/健康检查。 + + + +有几个横切关注点贯穿四层：**atlas**（代码图）、**lean** +（最小性 —— 既作为一个 tool 又作为一个 Stop-guard 交付，所以不管 +模型是否主动调用它都会生效），以及 **recall**（记忆）。 + +## Guard 胜过自然语言 + +模型允许漂离的规则活在自然语言里；模型**永远不能**打破的规则 +活在 guards 里（确定性 shell 钩子）。一个 guard 在上下文 +压缩之后也不会被遗忘。 + + + 把每一条可强制的不变量从 `CLAUDE.md` 里挪进一个 guard；让自然语言 + 尽量薄。这是 Forge 设计里最重要的一条纪律。 + + +## 已验证的跨工具输出矩阵 + +Forge 为**九个工具**输出配置，加上一个给 Roo Code 和 VS Code 的 MCP 服务器。每 +一行都对着厂商文档核对过。 + +| 工具 | 原生目标 | Forge 如何输出 | +| ------------------ | ---------------------------------------------------------------- | ---------------------------------------------------------------------- | +| **Claude Code** | `CLAUDE.md`（+ `.claude/rules/*.md`、`settings.json`） | 一份很薄的 `CLAUDE.md`，第一行是 `@AGENTS.md`；guards → settings | +| **Codex** | 原生的 `AGENTS.md`（32 KiB 上限） | 根目录下的规范 `AGENTS.md` **就是**那份来源 | +| **Cursor** | `AGENTS.md` + `.cursor/rules/*.mdc` | 扁平规则用 `AGENTS.md`；需要限定作用域时用 `.mdc` | +| **Gemini** | `GEMINI.md`，或通过 `context.fileName` 选择 `AGENTS.md` | 写一份 `.gemini/settings.json`，避免出现第二份副本 | +| **Aider** | 通过 `.aider.conf.yml` 里的 `read:` 引用 `CONVENTIONS.md` | 输出一份 `.aider.conf.yml`，里面 `read: AGENTS.md` | +| **Copilot** | 根目录 `AGENTS.md` + `.github/copilot-instructions.md` | 依赖根目录的 `AGENTS.md`；可选加一个 `.github` 指针 | +| **Windsurf/Devin** | 自动发现的 `AGENTS.md`（上限 6k/12k 字符） | 根目录 `AGENTS.md` 保持在上限之内；识别 `.windsurf` 或 `.devin` | +| **Zed** | 一个优先级列表里的第一个匹配，包括 `AGENTS.md` | 输出 `AGENTS.md`；doctor 会标出任何遮蔽它的老式文件 | +| **Continue** | `.continue/rules/*.md` + `.continue/mcpServers/*.yaml` | 输出一份 rules 文件，外加 Forge 的 MCP 服务器配置 | + +Roo Code 和 VS Code 通过 `forge init`（`.roo/mcp.json`、 +`.vscode/mcp.json`）拿到 Forge 的 MCP 服务器，而不是一份规则文件。 + + + **字符上限是真的存在。** Codex 在 32 KiB 处截断，Windsurf 在 6k/12k 处截断。 + `forge sync` 会强制一个源大小预算，避免配置被悄悄截断。 + diff --git a/mintlify/cn/concepts/cross-session-memory.mdx b/mintlify/cn/concepts/cross-session-memory.mdx new file mode 100644 index 0000000..c89f125 --- /dev/null +++ b/mintlify/cn/concepts/cross-session-memory.mdx @@ -0,0 +1,85 @@ +--- +title: "跨会话记忆" +description: "会话锚定、完成门、handoff 快照和决策日志 —— 用来终结会话失忆和半成品工作的一层。" +--- + +这一层存在的意义是要消灭两种失败模式：**半成品工作**（代码改了，但依赖 +它的产物没跟着改）和**会话失忆**（下一个会话把这一个知道的东西又假设了 +一遍）。指令只是提升正确行为的 _概率_；确定性的钩子才能保证一个 _底线_。 + +## 会话锚定 + +在 `SessionStart` 上（`src/session.js`），Forge 每次会话记录一次 `HEAD`，清理 +一周前的会话产物，并注入一份新鲜的定位信息： + + + + 从过去的修正中挖掘出来的 Cortex 经验。 + + + 既定的目标，好让漂移可以对着它衡量。 + + + 上一个会话写下的、有界的 `.forge/state.md`。 + + + 最近的提交和未提交的变更 —— 证据，而不是先验假设。 + + + +新会话是基于证据定位的，而不是基于先验。 + +## 完成门 + +Stop 路径上唯一有资格作出回应的 guard 是 `completion-gate.sh` +（`src/gate.js`）。它同步运行；负责挖掘经验的 `cortex.sh stop` 保持后台运行 +并永远不能阻塞。 + +变更集合是**会话范围**的：来自 committer 时间不早于会话开始时间的提交里的 +文件，加上工作区的变更，减去 `SessionStart` 时快照的脏东西 —— +所以已存在的编辑、切分支、`git pull` 都不会被算到代理头上。 + + + 如果代码动了，但没有对应的文档或状态产物跟进，这个门会**阻塞一次**， + 并以一份修复清单作为原因。其他所有情况都放行，任何内部错误 + 也都放行（fail-open）。`FORGE_STOPGATE=0` 可以关掉它。 + + +修复清单指向那些能收尾工作的工具： + +```bash +forge docs sync # sweep the diff for stale doc mentions +forge handoff "" --next "" # write the bounded session snapshot +forge decide " — " # record a choice so no session re-decides it +``` + +## Handoff 和 decisions + +两个存储把知识跨会话保留下来： + +| 存储 | 语义 | +| --------------------- | ------------------------------------------------------------------------------------ | +| `.forge/state.md` | 有界的**重写**（快照）—— 加载成本永远是 `O(bound)`。 | +| `.forge/decisions.md` | 只追加的 **ADR-lite**（`D-####`），带一份机器可读的决策账本副本。 | + +两者在写入时都拒收秘密。`state.md` 每次会话开始时会重新注入； +`decisions.md` 在重新决定过去某个会话已经定下的事情之前会被读一遍。 + +```bash +forge handoff "" --next "" +forge decide " — " +forge decide # read the log before re-deciding +``` + +## 由 diff 驱动的文档扫描 + +`forge docs sync` 回答一个 diff 形状的问题：变化过的标识符（路径、 +定义和被调用的符号，来自新增 _和_ 删除的行）对着每份文档 +产物扫描 → UPDATED / STALE（带 file:line 命中）/ VERIFIED-UNAFFECTED，并把 +原因记录下来。它只做汇报；牙齿由完成门提供。 + + + `recall` 和 `cortex` 只是文件加提示词的记忆 —— **不是**权重级别的学习。 + Consolidate 是一个可能产生幻觉的摘要器，所以它保持建议性、 + 可由人审阅、且不含秘密。 + diff --git a/mintlify/cn/concepts/model-routing.mdx b/mintlify/cn/concepts/model-routing.mdx new file mode 100644 index 0000000..635d69b --- /dev/null +++ b/mintlify/cn/concepts/model-routing.mdx @@ -0,0 +1,80 @@ +--- +title: "模型路由" +description: "在分发前，通过一份确定性、可 diff 的评分表挑出最便宜的能胜任的模型层 —— 并且对自建网关有一个安全回退的重映射。" +--- + +在分发**之前**，Forge 会根据一份你可以在仓库里读到的确定性评分表 +（`src/model_tiers.json`）为一个任务推荐最便宜的能胜任的模型。和那种 +在请求时由代理内部决定的网关不同，路由决策在 git 里是可见、可 diff 的。 + +## 推荐一个层 —— `forge route` + +```bash +forge route "" # cheapest capable model tier for the task +forge route gateway # emit LiteLLM gateway config +``` + +推荐依据是在一份带标签的样本库（英文 + Hinglish 行）上、 +在重叠相似度度量下、带一个置信度门槛的样本 k-NN 数学 —— 而不是关键词匹配。 + + + 从推荐的 `route.tier` 开始，只在某个外部验证器失败之后再升级， + 绝不预防性地升级。这样能在任务确实需要能力时不封顶能力， + 同时把开销压下去。 + + +## 先意图，再层级 + +路由和意图检测共享同一套数学（`src/intent.js`）：一段提示通过同一个样本 +k-NN 估计器被映射到某个意图。注意两者用的停用词集合不同 —— route +把通用动词（`fix` / `add` / `build`）视为复杂度噪音，但那些动词 +恰恰是意图的信号。 + +## 层级表 + +层级表（`src/model_tiers.json`）按家族（haiku / sonnet / opus / fable） +钉死了公开的 Anthropic 模型 ID。文档里的价格由文档检查 +对着这份文件核对，所以自然语言和表不会漂移。 + +## 自建网关的重映射 + +一个自建的 LiteLLM 或代理网关会用它自己的模型名，所以原封发送一个 +出厂 ID 会 404。当配置了非默认网关的 base URL 时，Forge +（`src/gateway_model_map.js`）会**每个进程一次**地 `GET /v1/models`，并把它 +公示的每个 id 对每一层的家族打分： + + + + 家族关键词（haiku / sonnet / opus / fable）必须匹配 —— 这是硬门槛。 + + + 在同一家族里，用该层名字 token 的 `setOverlap` 系数挑出 + 最佳匹配。 + + + 平局时倒向最接近规范名的 id。 + + + + + 只有当解析出来的 id 是 _出厂_ ID 时，重映射才会向网关请求 —— 一个显式的 + `.forge/providers.json` 别名或 `ANTHROPIC_MODEL` 覆盖永远不会 + 被动。它会在没有网关、无法访问 `/v1/models`，或没有匹配到家族时 + 安全地退回到出厂 ID，所以直连 `api.anthropic.com` 的用户是逐字节相同的。 + + +`forge doctor` 的 **gateway models** 一行会打印出解析后的 `tier → model` +映射，方便核对。 + +## 提供方与成本 + +```bash +forge config # show / switch / add providers, set the default model +forge cost # real per-day spend +forge cost --stages # measured per-stage cost factors +``` + + + `forge cost --stages` 只报告**实测的阶段** —— 一个没有事件记录的阶段会显示 + "no data"，绝不会给出默认值。数字在被实测之前只是一个假设。 + diff --git a/mintlify/cn/concepts/pre-action-gate.mdx b/mintlify/cn/concepts/pre-action-gate.mdx new file mode 100644 index 0000000..44af24a --- /dev/null +++ b/mintlify/cn/concepts/pre-action-gate.mdx @@ -0,0 +1,99 @@ +--- +title: "动作前门" +description: "forge substrate 在模型编辑代码之前跑一次有序的检查，并返回一个统一裁决 —— 假设、路由、影响、范围、记忆和验证。" +--- + +**认知基底** —— 在模型编辑代码之 _前_ 运行的一层。`forge substrate +""`（以及 MCP 工具 `substrate_check`）跑一次有序的检查，并返回一个统一 +裁决。它把可单独调用的阶段 —— `preflight`、`route`、`atlas`、`impact`、 +`reuse`、`context`、`scope`、`lean`、`anchor`、`verify` —— 组合成一份动作前 +契约。 + +```mermaid +flowchart TD + RE["referenced entities"] --> INTAKE + subgraph INTAKE["intake"] + direction LR + PF["preflight · assumption gap"] --> RT["route · cheapest tier"] + end + INTAKE --> ANALYSIS + subgraph ANALYSIS["analysis"] + direction LR + AT["atlas · code graph"] --> IM["impact · blast radius"] --> PT["predict · failing tests"] --> RU["reuse · cache hit?"] + end + ANALYSIS --> SAFETY + subgraph SAFETY["safety + fit"] + direction LR + CX["context · completeness gate"] --> SC["scope · coupled files"] --> ME["memory · recall + lessons"] --> MN["minimality · lean footprint"] --> GA["goal-anchor · drift check"] + end + SAFETY --> VD["verdict"] +``` + +## 三个阶段 + + + + **preflight** 找出假设缺口 —— 任务里点名了但仓库并未 + 定义的东西。**route** 挑出最便宜的能胜任的模型层。 + + + **atlas** 读取代码图，**impact** 计算爆炸半径，**predict** + 点名可能失败的测试，**reuse** 检查是否有已验证的缓存命中。 + + + **context** 跑完备性门，**scope** 揭示耦合文件，**memory** + 注入 recall + 经验，**minimality** 衡量 lean 足迹， + **goal-anchor** 检查漂移。 + + + +## 爆炸半径 + +**爆炸半径** —— 从代码图中读出的、一次编辑预测会影响的文件集合。 +`forge impact` 计算它；管线在模型触碰任何东西之前把它显示 +出来。 + +```bash +forge impact verifyToken # predicted impacted files for a symbol +forge impact src/auth.js # …or for a file +``` + +## 默认建议性 + +裁决**默认是建议性的** —— 它报告，不阻塞。设置 +`FORGE_ENFORCE=1` 就能把最强的信号变成硬阻塞： + + + + preflight 找不到可执行的意图 —— 任务表述不足。 + + + 完备性门盖不住预测的编辑集合。 + + + 受影响集合超过默认约 25 文件的阈值。 + + + +其他一切都保持为人可以覆盖的警告。 + + + 在 Claude Code 上，整个门会通过 `UserPromptSubmit` 钩子在**每次提示上 + 自动**运行 —— 对干净的任务保持静默。`forge substrate "" --json` + 给出可用于脚本的机器可读裁决。 + + +## 运行它 + +```bash +forge substrate "Change verifyToken in src/auth.js to require length > 20; update tests" +forge substrate "" --json +``` + +如果裁决是 `ASK FIRST`，在编辑前先问它返回的 `assumption.questions` —— +不要对一个表述不足的任务瞎猜。从推荐的 `route.tier` 开始，只在某个 +外部验证器失败之后再升级，绝不预防性地升级。 + + + 记忆阶段从那本携带证据的账本里读取。 + diff --git a/mintlify/cn/concepts/proof-carrying-memory.mdx b/mintlify/cn/concepts/proof-carrying-memory.mdx new file mode 100644 index 0000000..bd20923 --- /dev/null +++ b/mintlify/cn/concepts/proof-carrying-memory.mdx @@ -0,0 +1,113 @@ +--- +title: "携带证据的记忆" +description: "每一条被存下来的事实、经验或复用产物都是一个自带证据的声明 —— 只有当独立裁决者把它的置信度抬升到底线之上时才被信任。" +--- + +**Proof-carrying memory (PCM)** —— 每一条被存下来的事实、经验或复用产物都是一个 +_声明_，自带它的证据。只有当独立裁决者（测试、CI、人的 +接受/回退）把它的置信度抬升到底线之上时它才被信任。一条错误的经验会 +衰减掉，而不是被固化下来。 + + + "携带证据的记忆"是我们给**以证据为依据、按内容寻址的 + 记忆**起的名字 —— 一个由自身内容哈希寻址、并且链接到其 + 背后裁决者结果的声明。"proof"（证据）指的是这条证据链加上置信度规则， + **不是形式化机器可校验的证明**；回路里没有定理证明器。 + + +## 一份存储，多个写入者 + +所有记忆子系统都汇聚到同一份存储。`recall`、`remember`/`brain`、`cortex` +经验、`reuse` 产物和死循环 `diagnose` 结果都会把按内容寻址的 +声明写进 `.forge/ledger/`。 + +```mermaid +flowchart LR + subgraph EV["local events"] + direction TB + E1["recall / remember"] + E2["cortex lesson"] + E3["reuse mint"] + E4["diagnose"] + end + EV -->|"content-addressed claims"| LG["(.forge/ledger)"] + O["independent oracles · tests · CI · human accept/revert"] -->|"append evidence · move confidence"| LG + TM["teammate ledgers"] <-->|"git union-merge · conflict-free"| LG + LG --> RV["merged read view · recall list · lesson inject · brain index"] +``` + +## 为什么它无冲突地收敛 + +因为一个声明的字节内容是 `(kind, body, scope)` 的纯函数，每个副本都 +算出同一个身份 —— 所以队友的账本可以走普通 git 无冲突地合到一起。 + +机制上： + +- **证据和 tombstone 是只追加的**、哈希去重的日志。 +- **置信度（`val`）** 是一个带衰减的 Beta 后验，只有裁决者才能移动。 +- **合并是一个 join-semilattice** —— 已用性质测试证明是可交换、可结合、 + 幂等的 —— 所以账本无论以什么顺序都会收敛。 + + + `forge init` 会输出账本所需的 union-merge `.gitattributes` 规则；`forge + ledger merge ` 可以把任何另一个账本树合进来。完整决策记录在 + ADR-0006 (proof-carrying memory) 里。 + + +## 只有裁决者才能移动置信度 —— 别的都不行 + +只有独立的裁决者才能移动一条记忆的置信度： + + + + 一个通过的、能行使这条声明的测试，会抬高它的置信度。 + + + 一条绿灯的流水线是这条声明依然成立的独立证据。 + + + 人显式接受或直接回退是最强的信号。 + + + +无法验证的证据会被 `ORACLES` 表（`src/ledger.js`）里的封闭清单拒绝。 +未经审阅的知识会向 _不确定_ 衰减，而不是被删除 —— 沉睡的声明会 +保留下来用于审计，绝不会被悄悄移除。 + +## 账本表面 + +```bash +forge ledger stats # what the repo knows, by kind and trust level +forge ledger verify # re-check claims are in normal form +forge ledger show # a claim and its evidence trail +forge ledger blame # who minted it, every oracle outcome, per-author trust +forge ledger query "" # retrieve claims by relevance +forge ledger ratify # human accept +forge ledger retract # tombstone a claim +forge ledger merge # fold a teammate's ledger in, conflict-free +forge ledger import # bridge legacy stores into the ledger +``` + +加 `--personal` 是每用户的账本。 + +## reuse 缓存也是携带证据的 + +`forge reuse` 是一份携带证据的代码缓存。一件生成的产物只有当它的 +证据还成立时才会被再次交付出来 —— 置信度在底线之上，**且** +它的 atlas 依赖仍然可以解析。否则就会 fall through 到生成，并在 +返回的路上再生成一条新的声明。 + +```mermaid +flowchart LR + SP["spec"] --> FP["fingerprint · MinHash + LSH"] + FP --> LD["match ladder · exact to near to adapt to miss"] + LD --> GT{"confidence >= floor AND deps resolve?"} + GT -->|"yes"| SV["serve · proof holds"] + GT -->|"miss"| GN["generate"] + GN -->|"mint claim"| MT["(.forge/ledger)"] +``` + + + MinHash 的近似匹配在非常短的 spec 上比较弱。一个可选的 embeddings 后端 + （`FORGE_EMBED`）可以缓解这一点；MinHash 依然是零依赖的默认方案。 + diff --git a/mintlify/cn/concepts/verification-gates.mdx b/mintlify/cn/concepts/verification-gates.mdx new file mode 100644 index 0000000..a466a7f --- /dev/null +++ b/mintlify/cn/concepts/verification-gates.mdx @@ -0,0 +1,99 @@ +--- +title: "验证门" +description: "独立验证、幻觉符号标记、规范即契约以及技能门 —— 一些能减轻但从不认证正确性的检查。" +--- + +不跑一次可以复核的检查 —— 一个测试、一个构建退出码、一张截图 —— +就没有"完成"。Forge 的每一个验证门都多接住一次。设每个任务的漏检率 +为 `1 − p`，某个门的接住率为 `c`，那么被漏掉的错误会降到 `(1 − p)(1 − c)`， +这里每一个门都是多一个 `c`。 + + + **验证是减轻，不是认证。** Crew 验证者和幻觉符号 + 标记能减少评审负担；它们并不证明代码是正确的。测试和人的 + 修正永远拥有最终发言权。 + + +## 独立验证 —— `forge verify` + +一个独立的门：它跑仓库真正的测试、标出幻觉符号，并 +检查出处溯源。 + +```bash +forge verify # tests + hallucinated-symbol + provenance +forge verify --deep # multi-lens consensus — several independent checks must agree +``` + + + `--deep`（v0.19+）升级为一个多视角共识：变更必须过几个 + 独立的验证视角，而不只是一个。 + + +## 幻觉符号标记 —— `forge atlas has` + +`forge atlas has ` 是幻觉检查：如果模型调用了一个不在代码图里的 +符号，这个门会标出来。 + +```bash +forge atlas build # index this repo's symbols → .forge/atlas.json +forge atlas has useAuth # "not found" = likely hallucinated +``` + +atlas 有意做成纯 JSON —— Codex、Cursor、Gemini 和 Aider 都能通过 CLI 或 +简单的 `jq` 来读 `.forge/atlas.json`，消费端不需要依赖 MCP。 + +## 规范即契约 —— `forge spec` + +把行为钉在一份规范上，并检测相对它的漂移： + +```bash +forge spec init # scaffold an OpenSpec contract +forge spec lock # lock the current spec as the contract +forge spec check # report drift against the locked contract +``` + +## 技能门 —— `forge scan` + +在安装一个 skill 或 MCP 服务器之前，审核它是否有注入、RCE 或数据外泄的风险： + +```bash +forge scan +``` + + + 一次干净的扫描**不等于安全认证。** 内置启发式只能捕捉 + 已知的攻击形状（critical）和少数几种高严重度模式；通过意味着 _"没有检测到 + critical 特征"_，而不是 _"可以放心安装"_。始终自己审阅源码、 + 权限、包的来源和网络行为。一次 **high** 严重度的发现即便没有硬阻塞， + 也不会被标记为安全。外部扫描器是按需启用的，除非你打开，否则不会 + 发起任何网络调用。 + + +## 加固 —— `forge harden` + +接通把秘密和不安全变更挡在外面的安全控制： + +```bash +forge harden # gitleaks pre-commit + sandbox settings +``` + +## 提交级门 —— `forge precommit` + + + `forge precommit`（v0.19+）是一个提交级门 —— 它在提交时跑一遍验证底线， + 让部分完成或未验证的工作在落地之前就被拦住。 + + +## UI 检查 —— `forge uicheck` + +确定性的 UI 检查，前三个视角不需要 LLM 也不需要截图： + +```bash +forge uicheck contrast # WCAG contrast ratio +forge uicheck fingerprint # deterministic design fingerprint +forge uicheck design # slop-distance + conformance gate +forge uicheck visual # Playwright-rendered check (opt-in tier) +``` + +配合 `forge taste` 用来挑一个视觉方向（brutalist、corporate、 +editorial、minimalist、playful），并对 `design` 门的阈值做参数化。 diff --git a/mintlify/cn/guides/radar-deps.mdx b/mintlify/cn/guides/radar-deps.mdx new file mode 100644 index 0000000..5e82f8f --- /dev/null +++ b/mintlify/cn/guides/radar-deps.mdx @@ -0,0 +1,67 @@ +--- +title: "用 radar 保持依赖新鲜" +description: "forge radar 把你的依赖按新鲜程度分到多个环里，让陈旧或漂移中的依赖在咬人之前先浮出水面。" +--- + + + `forge radar` 正在 v0.19 线路上落地。这份指南描述它如何嵌入现有的 + 依赖新鲜度纪律；在你安装的版本里可用性以 `forge --help` 为准。 + + +Forge 的工程规则之一是：_在加一个依赖之前，从在线来源确认当下最佳 +的选项，并优先复用项目已经在用的东西。_ `forge radar` 把你依赖的 +当前状态可视化出来，好让这条规则有数据支撑。 + +## 想法：新鲜度环 + +`forge radar` 按每个依赖有多"新"把项目的依赖分到一圈圈**新鲜度环**里 —— +从中心的最新，到边缘的陈旧或漂移中。读这些环是一种快速回答 +"哪些东西我们让它漂了？"的方法，不用一个包一个包地手工审计。 + +```bash +forge radar +``` + +## 依赖列表从哪来 + +Radar 建立在同一套清单读取之上，它也是 `forge stack` 的动力，后者从 +仓库的依赖清单文件里探测它真实的技术栈： + +```bash +forge stack # languages, frameworks, package managers, real test commands +``` + +因为探测是数据驱动的，并且在各生态（`package.json`、 +`pyproject.toml`、`go.mod`、`Cargo.toml`、`Gemfile`、`composer.json`、`pom.xml` / +`build.gradle`、`*.csproj`）上是安全失败的，radar 可以对 `stack` 认得的 +同一批清单进行新鲜度推理。 + +## 在循环中使用它 + + + + 在添加或升级依赖之前，先跑一下 `forge radar`，看看哪些依赖 + 已经在漂了。 + + + 如果一个能胜任、又已经很新鲜的依赖已经在内圈里，那就复用它， + 而不是再加一个新的 —— 最能合身的最小变更胜出。 + + + 当你确实要升级或替换一个依赖时，把原因记录下来： + ```bash + forge decide "bump to — " + ``` + 这样将来的会话读到这份记录，而不是重新纠结一遍。 + + + + + Radar 报告新鲜度；它不会替你升级。把它的环当作一份供人做决定的 + 建议性输入 —— 任何一次升级在被称为完成之前，都要用仓库真正的 + 测试（`forge verify`）来验证一次。 + + + + 依赖升级之后，跑一遍 Quality 门 —— `forge verify` 和 `forge precommit`。 + diff --git a/mintlify/cn/guides/team-memory.mdx b/mintlify/cn/guides/team-memory.mdx new file mode 100644 index 0000000..f9aff91 --- /dev/null +++ b/mintlify/cn/guides/team-memory.mdx @@ -0,0 +1,79 @@ +--- +title: "用账本实现团队记忆" +description: "把队友的账本无冲突地合进来，走的是普通的 git —— 没有服务器，没有同步服务，只是文件，无论以什么顺序都会收敛。" +--- + +基底学到的一切 —— cortex 经验、`forge remember` 事实、已验证的 reuse +产物 —— 都以按内容寻址的声明形式落到一份 git 原生的账本（`.forge/ledger/`）里， +它被设计成合并时不会有冲突。没有服务器，也没有同步服务；只是 git 里的 +文件。 + +## 团队记忆三条命令 + + + + ```bash + forge init + ``` + 这会输出账本所需的 `.gitattributes` union-merge 规则等内容。 + + + Cortex 经验和 `forge remember` 事实会在你干活时把声明影子写进账本 —— + 不用额外跑什么。 + + + ```bash + git pull && forge ledger merge + ``` + 任何顺序都行 —— 合并是无冲突的。 + + + +## 为什么它不会冲突 + +一个声明的字节内容是 `(kind, body, scope)` 的纯函数，所以每个副本对 +同一份知识都算出同一个身份。合并是一个 join-semilattice —— 已用 +性质测试证明是可交换、可结合、幂等的 —— 所以两个队友的 +账本无论谁先同步都会收敛到相同的状态。 + +```mermaid +flowchart LR + A["your ledger"] <-->|"git union-merge · conflict-free"| B["teammate ledger"] + A --> M["merged read view"] + B --> M + M --> R["recall list · lesson inject · brain index"] +``` + + + 同一份知识被独立地铸造两次，会收敛到**一个**声明， + 并在它的出处里保留每一位作者。 + + +## 信任与出处 + +置信度只能被独立裁决者移动 —— 测试、CI、人的接受/回退 —— 所以 +导入一份队友的账本并不会盲目相信他们的笔记；它导入的是他们的 +_证据_。 + +```bash +forge ledger blame # who minted a claim, every oracle outcome, per-author trust +forge ledger stats # the merged view, by kind and trust level +forge ledger verify # confirm every claim is in normal form +``` + +## 跨团队复用 + +一旦队友已验证的代码进入了合并后的账本，你就可以带着它的证据来复用它： + +```bash +forge reuse query "" +``` + +一次命中指向的是有效、经测试确认过的代码，以及能证明它的 +`forge ledger blame` —— 复用它，而不是重新生成。 + + + 沉睡的声明会保留下来用于审计，绝不删除；未经审阅的知识 + 会向 _不确定_ 衰减，而不是向删除衰减。账本是一条证据链， + 不是一个可以被悄悄丢失的缓存。 + diff --git a/mintlify/cn/guides/zero-config-onboarding.mdx b/mintlify/cn/guides/zero-config-onboarding.mdx new file mode 100644 index 0000000..db52f1c --- /dev/null +++ b/mintlify/cn/guides/zero-config-onboarding.mdx @@ -0,0 +1,86 @@ +--- +title: "引导式、低配置的上手" +description: "五分钟就能上手：安装一次，一个仓库配置一次，做一个任务，然后看着账本从第二天开始回本 —— 是引导式、低配置，不是零操作。" +--- + +Forge 追求的是**引导式、低配置的上手** —— 一个新仓库通常能在大约五分钟内 +进入可干活状态。安装一次，一个仓库配置一次，做一个任务，然后账本从第二天开始 +回本。（是低配置，不是零配置：你仍然需要装 CLI，在每个仓库里跑 `forge init`， +一些路径会假设有 Bash、Git 和 `jq`。） + +```mermaid +flowchart TD + I["forge init"] --> Cfg["every tool configured from one source"] + Cfg --> Work["you work as usual"] + Work --> Gate["substrate checks each task · ask first? · which model? · what breaks?"] + Gate --> Edit["agent edits, with guardrails"] + Edit --> Learn["cortex learns from corrections"] + Learn -.->|next task is smarter| Work +``` + +## 1. 安装（一次） + +推荐的路径不需要 token 也不需要克隆： + + + +```bash Plugin +/plugin marketplace add CodeWithJuber/forgekit +/plugin install forgekit +``` + +```bash CLI +npm install -g @codewithjuber/forgekit +``` + + + +```bash +forge doctor # everything green? +``` + +## 2. 配置一个仓库（每个仓库一次） + +```bash +cd ~/your-project +forge init # emits AGENTS.md, CLAUDE.md, .gemini/settings.json, .aider.conf.yml … +``` + +现在 Claude Code、Codex、Cursor、Gemini、Aider、Copilot、Windsurf、Zed 和 Continue +都从各自的原生文件里读**同一份**规则。以后要改规则，就编辑 +`source/rules.json`（或者放一份仓库级的 `.forge/rules.json`），然后跑 `forge sync`。 + +## 3. 使用认知基底 + +```bash +forge substrate "" # ask/route/impact/scope/reuse/context/memory/verify in one pass +forge substrate "" --json +forge impact # the blast radius on its own +``` + +如果 `forge substrate` 返回 `ASK FIRST`，在编辑前先问它返回的问题。 + +## 4. 使用附加功能 + +```bash +forge atlas build # index this repo's symbols → .forge/atlas.json +forge atlas query useAuth # where is it defined? +forge atlas has useAuth # does it exist? "not found" = likely hallucinated +forge recall add "db port" "Postgres is on 5433 here, not 5432" +forge catalog # the Start-Here index of everything +``` + +## 5. 第二天：账本正在学习 + +第一天基底学到的一切 —— cortex 经验、被记住的事实、已验证的 +代码 —— 都以声明的形式落到了 `.forge/ledger/`。 + +```bash +forge ledger stats # what the repo knows, by kind and trust level +forge ledger blame # who minted a claim, every oracle outcome +forge reuse query "" # verified code you already have +``` + + + 接下来：把队友的账本无冲突地合进来，走的是普通的 git。 + diff --git a/mintlify/cn/installation.mdx b/mintlify/cn/installation.mdx new file mode 100644 index 0000000..6fd915a --- /dev/null +++ b/mintlify/cn/installation.mdx @@ -0,0 +1,105 @@ +--- +title: "安装" +description: "通往同一棵树的三个入口：插件市场、npm 全局安装，以及一个不走注册表的 github: 安装方式 —— 还有贡献者用的软链接开发方案。" +--- + +Forge 采用**一棵树，三个入口**的设计：插件清单、加固过的安装脚本 +和 npm 的 bin 全都指向同一份 `global/` + `source/` 树。 +选一个适合你工具的通道。 + +## 选择一个通道 + + + + 面向 Claude Code 和 Codex。护栏自动接通；无需手动合并。 + + + 面向任何工具。从公共 npm 注册表获取 `forge` CLI。 + + + 不需要注册表 —— 直接从仓库安装。 + + + 克隆 + `npm link`，或者用 `bash install.sh` 走软链接方案。 + + + +## 环境要求 + +- **Node.js >= 20** +- **零运行时依赖** —— 一切都是 Node 内置。可选层 + （`FORGE_EMBED` 向量嵌入、`uicheck visual` 用的 Playwright）是按需开启，不会加进 + 必需依赖。 + +## 插件市场 + +对 Claude Code 和 Codex 推荐这条路径，不需要 token 也不需要克隆： + +```bash +/plugin marketplace add CodeWithJuber/forgekit +/plugin install forgekit +``` + +插件通过 `${CLAUDE_PROJECT_DIR}` 把护栏接通，所以动作前门和 +完成门在后台就会触发。 + +## npm 全局 + +面向任何工具，来自公共 npm： + +```bash +npm install -g @codewithjuber/forgekit +forge doctor # everything green? +``` + +## 不走注册表的 github: 安装 + +```bash +npm install -g github:CodeWithJuber/forgekit +``` + +## 贡献者 / 本地开发 + + + +```bash npm link +git clone https://github.com/CodeWithJuber/forgekit.git +cd forgekit +npm link +``` + +```bash install.sh (symlink setup) +git clone https://github.com/CodeWithJuber/forgekit.git +cd forgekit +bash install.sh +``` + + + +安装脚本经过加固：幂等、基于软链接、带备份，没有 `curl | sh`。 + +## 验证 + +不管你用了哪个通道，都可以确认安装状态： + +```bash +forge doctor # tools, guards, MCP auth, config drift, update status +``` + + + `forge doctor` 也会为 git 克隆版本给出一条不烦人的"落后上游多少提交"的提示。 + 设置 `FORGE_NO_UPDATE_CHECK=1` 可以让它安静下来。所有路径都是 fail-open —— + 离线或 detached HEAD 都会报告"unknown"，永远不会报错。 + + +## 保持 Forge 最新 + +```bash +forge update --check # report whether a newer version is available +forge update # apply the update (git checkout or npm/copy install) +forge update --to # pin or downgrade to a specific version +``` + + + 去快速开始，运行 `forge init` 和你的第一次基底检查。 + diff --git a/mintlify/cn/introduction.mdx b/mintlify/cn/introduction.mdx new file mode 100644 index 0000000..db31d9b --- /dev/null +++ b/mintlify/cn/introduction.mdx @@ -0,0 +1,132 @@ +--- +title: "简介" +description: "Forge 是每个无状态模型都缺失的认知基底 —— 记忆、预见和护栏 —— 以原生配置的形式交付到每一个 AI 编码代理。" +--- + +**为每个 AI 编码代理提供一个共同的大脑。** 大语言模型是无状态的：每次调用只有一个 +上下文窗口，之后就会被清空。它没有关于你团队所学的记忆，没有关于某次编辑会破坏什么的 +预见能力，也没有强制执行的护栏。Forge +(`@codewithjuber/forgekit`) 就是这层**认知基底** —— 在模型编辑代码之 +_前_ 运行的一层，提供以证据为依据、按内容寻址的记忆（我们 +称之为"proof-carrying memory"，携带证据的记忆）、启发式的影响预见，以及强制执行的护栏 —— +并且是一个**跨工具的配置编译器**，一次性把这个大脑作为原生配置交付到每个工具。 +Claude Code 是测试最深入的集成；其他工具也接收原生配置和 +MCP 工具，但真实场景下的锤炼较少。 + + + + 携带证据的记忆，可以在会话之间和团队成员之间持续存在。每一条经验、 + 事实和已验证的复用，都是一个自带证据的声明。 + + + 一次编辑的爆炸半径 —— 从代码图中读取到的、这次编辑预测会触及的文件集合， + 包括你从未点名的耦合文件。 + + + 确定性的钩子强制执行模型永远不能违反的规则。它们能挺过上下文压缩，而 + 配置文件中的自然语言规则则不能。 + + + +## 问题所在 + +大语言模型是无状态的 —— 每次调用只有一个上下文窗口，之后就会被清空。 + +- 它对你团队已经学到的东西**没有记忆**。 +- 它对一次编辑会破坏什么**没有预见**。 +- 它**没有强制执行的护栏** —— 自然语言的规则在一次压缩之后就会被遗忘。 + +而且每个工具都想要它自己的配置文件（`CLAUDE.md`、`AGENTS.md`、`.cursor/rules`、 +`GEMINI.md`、MCP……）。Forge 就是那层认知基底，补上这三样缺失的东西， +并作为编译器，从一份来源把它们分发到每个工具。 + +## 核心论点 + +模型无法在两次调用之间从你的代码库里学到东西：它的权重被冻结，工作记忆也 +在每次响应之后被清空。记忆、预见和自我检查 +无法通过提示词灌进去 —— 它们必须从 _外部_ 提供。那层外部东西 +就是认知基底。形式化地说，推理是一个固定的函数 `y = f(x)`，两次调用之间没有 +状态；Forge 就是那份状态。 + + + + 把你的规则和基底默认值写在一份规范来源里 + （`source/rules.json`、`source/substrate.json`、`source/mcp.json`）。 + + + `forge sync` 把这份来源编译成每个工具的原生配置 —— 九个 AI 编码 + 工具加上 MCP —— 带一个内容哈希头，所以漂移是可探测的，重复运行 + 是幂等的。 + + + `forge substrate ""` 运行一次确定性的动作前检查：假设、 + 路由、复用、上下文、爆炸半径、范围和目标锚点。 + + + 只有独立的裁决者 —— 测试、CI、人的接受/回退 —— 才能移动记忆 + 的置信度，所以错误的经验会衰减掉，而不是被固化下来。 + + + +## 你会得到什么 + +- **在会话之间和团队成员之间持续存在的记忆。** 每一条经验、事实和 + 已验证的复用都是 _proof-carrying memory (PCM)_ —— 我们给以证据为依据、 + 按内容寻址的记忆起的名字：一个声明，携带着它所依据的证据引用，只有当独立 + 裁决者把它的置信度抬升到某个底线之上时才被信任。"proof"（证据）指的是 + 这条证据链，而不是形式化证明。 +- **在把东西弄坏之前的预见能力。** 问一句"改动 `verifyToken` 会破坏什么？" + 就能从代码图里得到爆炸半径，包括你从未点名的耦合文件。 +- **不会被遗忘的护栏。** 确定性的钩子强制保护路径、 + 成本预算和死循环检测 —— 它们能挺过上下文压缩。 +- **从头到尾能够完成的工作。** 一个完成门在每个会话中会阻塞一次"完成" + —— 当代码动了但没有对应的文档或状态产物跟进时，答复里就带着修复清单。 +- **一份配置服务 9 个工具。** 规则只写一次；Forge 会输出每个工具的原生 + 配置，加上给 Roo 和 VS Code 的 MCP。零运行时依赖 —— 一个 Node CLI， + git 里的纯文本文件，不需要服务器。 + +## Forge 给哪些工具喂配置？ + +Forge 为**九个工具**输出配置，加上给 Roo Code 和 VS Code 的一个 MCP 服务器： +Claude Code、Codex、Cursor、Gemini、Aider、Copilot、Windsurf/Devin、Zed 和 Continue。 +每个工具从它自己的原生文件里读同一份规则。 + +## 诚实的边界 + +Forge 到处都会声明它自己的天花板。 + + + Forge **减轻但不消除**规则漂移。它是一层透明度和可靠性 + 的加成，不能取代测试、评审或判断。 + + +- **护栏只能强制那些能表达成钩子的规则**（路径、格式、diff 大小、 + 预算）。语义规则（"偏好函数式"）仍然是自然语言，有时会被忽略。 +- **验证是减轻，不是认证。** Crew 验证者和幻觉符号 + 标记能减少评审负担；它们并不证明代码是正确的。 +- **不做权重级别的学习。** `recall` / `cortex` 只是文件加提示词的记忆 —— 没有 + RL，没有微调。 +- **影响图是基于正则的近似** —— 保守，但不是严格意义上的调用图。 +- **测试和人的修正永远拥有最终发言权。** + + + Forge 目前是 **beta** 阶段。核心（`init`、`sync`、`substrate`、`impact`、`ledger`、护栏） + 已经过测试并在日常使用中；一些标志可能会在 `1.0` 前变化。 + + +## 下一步 + + + + 安装，运行 `forge init`，然后让你的第一个任务过一次基底。 + + + 四层编译器、携带证据的记忆和动作前门。 + + + 每一条命令，按 Core、Memory、Substrate、Quality 和 Config 分组。 + + + 把队友的账本无冲突地合进来，走的是普通的 git。 + + diff --git a/mintlify/cn/quickstart.mdx b/mintlify/cn/quickstart.mdx new file mode 100644 index 0000000..321b955 --- /dev/null +++ b/mintlify/cn/quickstart.mdx @@ -0,0 +1,106 @@ +--- +title: "快速开始" +description: "安装 Forge，从一份来源为每个工具生成配置，然后运行你的第一次动作前检查 —— 大约需要 60 秒。" +--- + +大约一分钟内，从零走到一个配置完毕的仓库，并跑完你的第一次基底检查。 + +## 1. 安装 + + + +```bash Plugin (Claude Code / Codex) +/plugin marketplace add CodeWithJuber/forgekit +/plugin install forgekit +``` + +```bash npm (any tool) +npm install -g @codewithjuber/forgekit +``` + +```bash No registry +npm install -g github:CodeWithJuber/forgekit +``` + + + +对 Claude Code 和 Codex，推荐走插件路径 —— 护栏会自动接通， +没有什么需要手动合并。完整的方案矩阵，包括开发用的软链接方式，见 +[安装](/cn/installation)。 + +## 2. 配置一个仓库 + + + + ```bash + cd ~/your-project + forge init + ``` + 这会生成 `AGENTS.md`、`CLAUDE.md`、`.gemini/settings.json`、`.aider.conf.yml` 等 + 文件 —— 以及账本所需的 `.gitattributes` union-merge 规则。Claude Code、 + Codex、Cursor、Gemini、Aider、Copilot、Windsurf、Zed 和 Continue 现在都从各自的 + 原生文件里读**同一份**规则。 + + + ```bash + forge doctor + ``` + 对已安装工具、护栏、MCP 认证和配置漂移做一次通过/失败检查。 + + + 编辑 `source/rules.json`（或者放一份仓库级的 `.forge/rules.json`），然后重新编译： + ```bash + forge sync + ``` + `sync` 是幂等的 —— 只会重写发生变化的部分。 + + + +## 3. 运行动作前门 + +基底就是那层在模型编辑代码之 _前_ 运行的东西。一条命令跑完整个门： + +```bash +forge substrate "Change verifyToken in src/auth.js to require length > 20; update tests" +# → assumption verdict · cheapest capable model · predicted blast radius +# (including files you didn't name) · scope clusters · verification checklist +``` + + + 在 Claude Code 上，基底会通过 `UserPromptSubmit` 钩子在**每次提示上自动**运行 —— + 只是建议性的，对干净的任务保持静默。其他所有工具都会拿到一条原生配置规则， + 加上 19 个可以自行调用的 MCP 工具。 + + +如果 `forge substrate` 返回 `ASK FIRST`，在编辑前先问它返回的问题。在做任何 +修改性变更之前，先读一读预测的受影响文件 —— 即爆炸半径。 + +```bash +forge substrate "" --json # machine-readable verdict +forge impact # the blast radius on its own +``` + +## 4. 探索附加功能 + +```bash +forge atlas build # index this repo's symbols → .forge/atlas.json +forge atlas query useAuth # where is it defined? (cheaper than grep-and-read) +forge atlas has useAuth # does it exist? "not found" = likely hallucinated +forge recall add "db port" "Postgres is on 5433 here, not 5432" +forge catalog # the Start-Here index of everything +``` + +## 5. 第二天：账本正在学习 + +第一天基底学到的所有东西，都以声明的形式落到了 `.forge/ledger/`。这 +就是携带证据的记忆 —— 从现在开始它要开始回报你了： + +```bash +forge ledger stats # what the repo knows, by kind and trust +forge ledger blame # who minted a claim, every oracle outcome +forge reuse query "" # verified code you already have +``` + + + 阅读动作前门如何把它的各个阶段组合成一个统一的裁决。 + diff --git a/mintlify/docs.json b/mintlify/docs.json index babbc87..4100b2d 100644 --- a/mintlify/docs.json +++ b/mintlify/docs.json @@ -16,55 +16,346 @@ "default": "system" }, "navigation": { - "tabs": [ + "languages": [ { - "tab": "Documentation", - "icon": "book-open", - "groups": [ + "language": "en", + "default": true, + "tabs": [ { - "group": "Get started", - "pages": ["introduction", "quickstart", "installation"] + "tab": "Documentation", + "icon": "book-open", + "groups": [ + { + "group": "Get started", + "pages": ["introduction", "quickstart", "installation"] + }, + { + "group": "Core concepts", + "pages": [ + "concepts/config-compiler", + "concepts/proof-carrying-memory", + "concepts/pre-action-gate", + "concepts/cross-session-memory", + "concepts/verification-gates", + "concepts/model-routing" + ] + } + ] + }, + { + "tab": "CLI reference", + "icon": "terminal", + "groups": [ + { + "group": "Reference", + "pages": [ + "cli/overview", + "cli/core", + "cli/memory", + "cli/substrate", + "cli/quality", + "cli/config" + ] + } + ] + }, + { + "tab": "Guides", + "icon": "compass", + "groups": [ + { + "group": "Guides", + "pages": [ + "guides/zero-config-onboarding", + "guides/team-memory", + "guides/radar-deps" + ] + } + ] + } + ] + }, + { + "language": "cn", + "tabs": [ + { + "tab": "文档", + "icon": "book-open", + "groups": [ + { + "group": "开始使用", + "pages": ["cn/introduction", "cn/quickstart", "cn/installation"] + }, + { + "group": "核心概念", + "pages": [ + "cn/concepts/config-compiler", + "cn/concepts/proof-carrying-memory", + "cn/concepts/pre-action-gate", + "cn/concepts/cross-session-memory", + "cn/concepts/verification-gates", + "cn/concepts/model-routing" + ] + } + ] + }, + { + "tab": "CLI 参考", + "icon": "terminal", + "groups": [ + { + "group": "参考", + "pages": [ + "cn/cli/overview", + "cn/cli/core", + "cn/cli/memory", + "cn/cli/substrate", + "cn/cli/quality", + "cn/cli/config" + ] + } + ] + }, + { + "tab": "指南", + "icon": "compass", + "groups": [ + { + "group": "指南", + "pages": [ + "cn/guides/zero-config-onboarding", + "cn/guides/team-memory", + "cn/guides/radar-deps" + ] + } + ] + } + ] + }, + { + "language": "ar", + "tabs": [ + { + "tab": "التوثيق", + "icon": "book-open", + "groups": [ + { + "group": "ابدأ", + "pages": ["ar/introduction", "ar/quickstart", "ar/installation"] + }, + { + "group": "المفاهيم الأساسية", + "pages": [ + "ar/concepts/config-compiler", + "ar/concepts/proof-carrying-memory", + "ar/concepts/pre-action-gate", + "ar/concepts/cross-session-memory", + "ar/concepts/verification-gates", + "ar/concepts/model-routing" + ] + } + ] + }, + { + "tab": "مرجع CLI", + "icon": "terminal", + "groups": [ + { + "group": "المرجع", + "pages": [ + "ar/cli/overview", + "ar/cli/core", + "ar/cli/memory", + "ar/cli/substrate", + "ar/cli/quality", + "ar/cli/config" + ] + } + ] }, { - "group": "Core concepts", - "pages": [ - "concepts/config-compiler", - "concepts/proof-carrying-memory", - "concepts/pre-action-gate", - "concepts/cross-session-memory", - "concepts/verification-gates", - "concepts/model-routing" + "tab": "الأدلة", + "icon": "compass", + "groups": [ + { + "group": "الأدلة", + "pages": [ + "ar/guides/zero-config-onboarding", + "ar/guides/team-memory", + "ar/guides/radar-deps" + ] + } ] } ] }, { - "tab": "CLI reference", - "icon": "terminal", - "groups": [ - { - "group": "Reference", - "pages": [ - "cli/overview", - "cli/core", - "cli/memory", - "cli/substrate", - "cli/quality", - "cli/config" + "language": "hi", + "tabs": [ + { + "tab": "दस्तावेज़", + "icon": "book-open", + "groups": [ + { + "group": "शुरू करें", + "pages": ["hi/introduction", "hi/quickstart", "hi/installation"] + }, + { + "group": "मूल अवधारणाएँ", + "pages": [ + "hi/concepts/config-compiler", + "hi/concepts/proof-carrying-memory", + "hi/concepts/pre-action-gate", + "hi/concepts/cross-session-memory", + "hi/concepts/verification-gates", + "hi/concepts/model-routing" + ] + } + ] + }, + { + "tab": "CLI संदर्भ", + "icon": "terminal", + "groups": [ + { + "group": "संदर्भ", + "pages": [ + "hi/cli/overview", + "hi/cli/core", + "hi/cli/memory", + "hi/cli/substrate", + "hi/cli/quality", + "hi/cli/config" + ] + } + ] + }, + { + "tab": "गाइड", + "icon": "compass", + "groups": [ + { + "group": "गाइड", + "pages": [ + "hi/guides/zero-config-onboarding", + "hi/guides/team-memory", + "hi/guides/radar-deps" + ] + } ] } ] }, { - "tab": "Guides", - "icon": "compass", - "groups": [ - { - "group": "Guides", - "pages": [ - "guides/zero-config-onboarding", - "guides/team-memory", - "guides/radar-deps" + "language": "zh", + "tabs": [ + { + "tab": "文档", + "icon": "book-open", + "groups": [ + { + "group": "开始使用", + "pages": ["zh-CN/introduction", "zh-CN/quickstart", "zh-CN/installation"] + }, + { + "group": "核心概念", + "pages": [ + "zh-CN/concepts/config-compiler", + "zh-CN/concepts/proof-carrying-memory", + "zh-CN/concepts/pre-action-gate", + "zh-CN/concepts/cross-session-memory", + "zh-CN/concepts/verification-gates", + "zh-CN/concepts/model-routing" + ] + } + ] + }, + { + "tab": "CLI 参考", + "icon": "terminal", + "groups": [ + { + "group": "参考", + "pages": [ + "zh-CN/cli/overview", + "zh-CN/cli/core", + "zh-CN/cli/memory", + "zh-CN/cli/substrate", + "zh-CN/cli/quality", + "zh-CN/cli/config" + ] + } + ] + }, + { + "tab": "指南", + "icon": "compass", + "groups": [ + { + "group": "指南", + "pages": [ + "zh-CN/guides/zero-config-onboarding", + "zh-CN/guides/team-memory", + "zh-CN/guides/radar-deps" + ] + } + ] + } + ] + }, + { + "language": "zh-Hans", + "tabs": [ + { + "tab": "文档", + "icon": "book-open", + "groups": [ + { + "group": "开始使用", + "pages": ["zh-Hans/introduction", "zh-Hans/quickstart", "zh-Hans/installation"] + }, + { + "group": "核心概念", + "pages": [ + "zh-Hans/concepts/config-compiler", + "zh-Hans/concepts/proof-carrying-memory", + "zh-Hans/concepts/pre-action-gate", + "zh-Hans/concepts/cross-session-memory", + "zh-Hans/concepts/verification-gates", + "zh-Hans/concepts/model-routing" + ] + } + ] + }, + { + "tab": "CLI 参考", + "icon": "terminal", + "groups": [ + { + "group": "参考", + "pages": [ + "zh-Hans/cli/overview", + "zh-Hans/cli/core", + "zh-Hans/cli/memory", + "zh-Hans/cli/substrate", + "zh-Hans/cli/quality", + "zh-Hans/cli/config" + ] + } + ] + }, + { + "tab": "指南", + "icon": "compass", + "groups": [ + { + "group": "指南", + "pages": [ + "zh-Hans/guides/zero-config-onboarding", + "zh-Hans/guides/team-memory", + "zh-Hans/guides/radar-deps" + ] + } ] } ] diff --git a/mintlify/hi/cli/config.mdx b/mintlify/hi/cli/config.mdx new file mode 100644 index 0000000..c4a1422 --- /dev/null +++ b/mintlify/hi/cli/config.mdx @@ -0,0 +1,91 @@ +--- +title: "Config कमांड्स" +description: "प्रोवाइडर्स, लागत, डैशबोर्ड्स, ब्रांड, atlas, और स्टैक: config, cost, dash, brand, atlas, stack — साथ ही v0.19+ report और tools कमांड्स।" +--- + +Config समूह प्रोवाइडर्स, ऑब्ज़र्वेबिलिटी, कोड ग्राफ़, और स्टैक डिटेक्शन को कवर करता है। + +## `forge config` + +प्रोवाइडर सेटअप — प्रोवाइडर्स दिखाएँ / स्विच करें / जोड़ें, डिफ़ॉल्ट मॉडल सेट करें। + +```bash +forge config # show current config +forge config switch +forge config add +``` + +## `forge cost` + +मापित स्टेज फ़ैक्टर्स के माध्यम से वास्तविक प्रति-दिन खर्च। + +```bash +forge cost # real per-day spend +forge cost --stages # measured per-stage cost factors +``` + + + **केवल मापित चरणों** की रिपोर्ट करता है — बिना घटनाओं वाला चरण "no data" कहता है, + कभी कोई डिफ़ॉल्ट नहीं। + + +## `forge dash` + +लेजर, मीट्रिक्स, और ब्लास्ट रेडियस पर लोकल डैशबोर्ड। + +```bash +forge dash # localhost-only, read-only (default port 4242) +``` + +## `forge brand` + +सक्रिय ब्रांड टोकन मैप प्रिंट करें। + +```bash +forge brand +``` + +ब्रांड एक टोकन (`brand.json`) के रूप में संग्रहीत है; रीब्रांड एक ही संपादन है। + +## `forge atlas` + +कोड ग्राफ़ बनाएँ / क्वेरी करें। + +```bash +forge atlas build [path] # walk the tree → .forge/atlas.json +forge atlas query "what calls Z" +forge atlas has # hallucinated-symbol check +``` + +atlas सादा JSON है — कोई भी टूल पढ़ता है, MCP आवश्यक नहीं। + +## `forge stack` + +इस रेपो के मैनिफ़ेस्ट से इसका वास्तविक स्टैक पहचानें। + +```bash +forge stack +``` + +`package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `Gemfile`, +`composer.json`, `pom.xml` / `build.gradle`, और `*.csproj` पढ़ता है, और भाषाएँ, +फ़्रेमवर्क, पैकेज मैनेजर, और रेपो की **वास्तविक** टेस्ट कमांड्स रिपोर्ट करता है — जो +सब्सट्रेट की सत्यापन चेकलिस्ट को फ़ीड करते हैं। + +## `forge report` v0.19+ + +रेपो की Forge स्थिति की एक स्टैटिक HTML रिपोर्ट बनाएँ — लेजर, मीट्रिक्स, और ब्लास्ट +रेडियस एक स्व-निहित फ़ाइल में प्रस्तुत जिसे आप साझा या संग्रह कर सकते हैं। + +```bash +forge report +``` + +## `forge tools` v0.19+ + +इस रेपो का प्राथमिक AI कोडिंग टूल चुनें और मिलती-जुलती `.gitignore` प्रविष्टियाँ वायर करें, +ताकि आपके सेटअप के लिए जनरेट की गई कॉन्फ़िग और `.forge/` आर्टिफ़ैक्ट सही ढंग से अनदेखे हों। + +```bash +forge tools +``` diff --git a/mintlify/hi/cli/core.mdx b/mintlify/hi/cli/core.mdx new file mode 100644 index 0000000..fd6630a --- /dev/null +++ b/mintlify/hi/cli/core.mdx @@ -0,0 +1,77 @@ +--- +title: "Core कमांड्स" +description: "रेपो बूटस्ट्रैप और रखरखाव करें: init, sync, doctor, catalog, docs, और update।" +--- + +Core समूह एक रेपो को बूटस्ट्रैप करता है और उसे स्वस्थ रखता है। + +## `forge init` + +इस रेपो का कॉन्फ़िग स्कैफ़ोल्ड करें — एक साझा स्रोत से हर टूल का कॉन्फ़िग निकालता है। + +```bash +forge init +``` + +`AGENTS.md`, `CLAUDE.md`, `.gemini/settings.json`, `.aider.conf.yml`, और बाकी +निकालता है (साथ ही Roo Code और VS Code के लिए MCP सर्वर कॉन्फ़िग), और लेजर के लिए +आवश्यक `.gitattributes` यूनियन-मर्ज नियम। + +## `forge sync` + +कैननिकल स्रोत को हर टूल की नेटिव कॉन्फ़िग फ़ाइलों में पुनः कंपाइल करें। + +```bash +forge sync +``` + +Idempotent — यह केवल वही पुनर्लिखित करता है जो बदला है। `source/rules.json` या +प्रति-रेपो `.forge/rules.json` संपादित करने के बाद इसे चलाएँ। + +## `forge doctor` + +इंस्टॉल किए गए टूल्स, गार्ड्स, MCP ऑथ, और कॉन्फ़िग ड्रिफ्ट की हेल्थ-चेक। + +```bash +forge doctor +``` + +टूल्स, गार्ड्स, MCP वायरिंग, कॉन्फ़िग ड्रिफ्ट, और अपडेट स्थिति पर पास/फ़ेल। हर पथ +fail-open है। जब कोई कस्टम gateway कॉन्फ़िगर हो तो एक **gateway models** पंक्ति +हल किए गए `tier → model` मैपिंग को प्रिंट करती है। + +## `forge catalog` + +Start Here — हर टूल, क्रू, और गार्ड को एक-पंक्ति कारण के साथ सूचीबद्ध करें। + +```bash +forge catalog +``` + +## `forge docs` + +Docs ↔ code ड्रिफ्ट। + +```bash +forge docs check # registry reconcile — commands, env vars, MCP tools, CHANGELOG +forge docs sync # diff-driven stale-docs sweep +``` + + + `docs check` CI को fail करता है जब कमांड्स, env vars, MCP टूल्स, या CHANGELOG + कोड से ड्रिफ्ट करते हैं। `docs sync` diff को स्वीप करता है और UPDATED / STALE / + VERIFIED-UNAFFECTED रिपोर्ट करता है। + + +## `forge update` + +तीनों इंस्टॉल मोड्स में सेल्फ़-अपडेट। + +```bash +forge update # apply the update (git checkout or npm/copy install) +forge update --check # report whether a newer version is available +forge update --to # pin or downgrade to a specific version (v0.19+) +``` + +हर पथ fail-open है — ऑफ़लाइन, कोई upstream नहीं, या detached HEAD "unknown" लौटाता है, +कभी कोई error नहीं। `FORGE_NO_UPDATE_CHECK=1` doctor सूचना को शांत करता है। diff --git a/mintlify/hi/cli/memory.mdx b/mintlify/hi/cli/memory.mdx new file mode 100644 index 0000000..227e4ee --- /dev/null +++ b/mintlify/hi/cli/memory.mdx @@ -0,0 +1,107 @@ +--- +title: "Memory कमांड्स" +description: "क्रॉस-सेशन और टीम मेमोरी: cortex, recall, remember, brain, ledger, reuse, handoff, और decide — ये सभी प्रूफ-कैरीइंग लेजर पर संगमित होते हैं।" +--- + +Memory समूह क्रॉस-सेशन और टीम मेमोरी का प्रबंधन करता है। इसकी सारी सामग्री +`.forge/ledger/` के प्रूफ-कैरीइंग लेजर पर संगमित होती है। मॉडल के लिए +[Proof-carrying memory](/hi/concepts/proof-carrying-memory) देखें। + +## `forge cortex` + +स्व-सुधार करने वाली प्रोजेक्ट मेमोरी — सुधारों से खनन किए गए सबक। + +```bash +forge cortex status # what's been learned +forge cortex why # why a lesson applies here +``` + +## `forge recall` + +क्रॉस-सेशन व्यक्तिगत मेमोरी प्रबंधित करें। + +```bash +forge recall list # facts the recall-load guard injects next session +forge recall add "db port" "Postgres is on 5433 here, not 5432" +forge recall consolidate # summarize (advisory, human-reviewable) +``` + +## `forge remember` + +इस रेपो की पोर्टेबल मेमोरी में एक टिकाऊ, रेपो-कमिटेबल तथ्य जोड़ें। + +```bash +forge remember "" +``` + +## `forge brain` + +पोर्टेबल प्रोजेक्ट-मेमोरी इंडेक्स दिखाएँ या पुनर्निर्मित करें। + +```bash +forge brain # show the index +forge brain --rebuild # rebuild it +``` + +## `forge ledger` + +प्रूफ-कैरीइंग मेमोरी — कंटेंट-एड्रेस्ड क्लेम स्टोर। + +```bash +forge ledger stats # what the repo knows, by kind and trust level +forge ledger verify # re-check claims are in normal form +forge ledger show # a claim and its evidence +forge ledger blame # who minted it, every oracle outcome, per-author trust +forge ledger query "" # retrieve by relevance +forge ledger ratify # human accept +forge ledger retract # tombstone a claim +forge ledger merge # fold a teammate's ledger in, conflict-free +forge ledger import # bridge legacy stores into the ledger +``` + +प्रति-यूज़र लेजर के लिए `--personal` जोड़ें। + +## `forge reuse` + +प्रूफ-कैरीइंग कोड कैश — केवल तब सर्व किया जाता है जब उसका साक्ष्य अब भी वैध हो। + +```bash +forge reuse query "" # verified code you already have +forge reuse mint "" --file # add an artifact to the cache +forge reuse stats # cache stats +``` + +## `forge handoff` + +सीमित सत्र स्नैपशॉट — `.forge/state.md` को पुनर्लिखता है, हर सत्र-आरंभ पर पुनः इंजेक्ट किया जाता है। + +```bash +forge handoff "" --next "" +``` + +## `forge decide` + +केवल-जोड़ने-वाला निर्णय लॉग — `.forge/decisions.md` में `D-####` ADR-lite प्रविष्टियाँ। + +```bash +forge decide " — " +forge decide # read the log before re-deciding +``` + +## `forge know` v0.19+ + +किसी तथ्य को उसके सही स्टोरेज गंतव्य पर रूट करें — यह तय करता है कि ज्ञान का एक टुकड़ा +`recall`, `remember`/`brain`, एक निर्णय, या एक cortex सबक में रहना चाहिए, और उसे वहाँ दर्ज करता है। + +```bash +forge know "" +``` + +## `forge deja` v0.19+ + +समान-पिछले-कार्य की खोज — लेजर में पूर्व कार्य को सतह पर लाता है जो उससे मेल खाता है +जो आप करने वाले हैं, ताकि आप पुनर्जनन के बजाय प्रमाण का पुनरुपयोग करें। + +```bash +forge deja "" +``` diff --git a/mintlify/hi/cli/overview.mdx b/mintlify/hi/cli/overview.mdx new file mode 100644 index 0000000..f6981fe --- /dev/null +++ b/mintlify/hi/cli/overview.mdx @@ -0,0 +1,61 @@ +--- +title: "CLI अवलोकन" +description: "हर forge कमांड, Core, Memory, Substrate, Quality, और Config के अनुसार समूहित — कमांड सतह डेटा है, जिसे एक कड़ी ड्रिफ्ट चेक द्वारा डॉक्स के विरुद्ध सुलझाया जाता है।" +--- + +`forge` कमांड सतह डेटा (`src/commands.js`) के रूप में परिभाषित है और `forge docs check` +द्वारा डॉक्स के विरुद्ध सुलझाई जाती है, इसलिए कोई कमांड डॉक्स की जानकारी के बिना +न शिप हो सकती है, न ग़ायब हो सकती है। कमांड्स को पाँच समूहों में संगठित किया गया है। + + + + बूटस्ट्रैप और रखरखाव: `init`, `sync`, `doctor`, `catalog`, `docs`, `update`। + + + क्रॉस-सेशन और टीम मेमोरी: `cortex`, `recall`, `remember`, `brain`, `ledger`, + `reuse`, `handoff`, `decide`। + + + प्री-एक्शन गेट और उसके चरण: `substrate`, `preflight`, `route`, `impact`, + `scope`, `context`, `anchor`, `diagnose`, `imagine`, `lean`। + + + सत्यापन और सुरक्षा: `verify`, `scan`, `spec`, `taste`, `uicheck`, `harden`। + + + प्रोवाइडर्स, लागत, डैशबोर्ड्स, ब्रांड, atlas, स्टैक: `config`, `cost`, `dash`, `brand`, + `atlas`, `stack`। + + + +## परिपाटियाँ + +- **डिफ़ॉल्ट रूप से सलाहकारी।** सबसे मज़बूत संकेतों (खोखला प्रॉम्प्ट, असंयोजनीय + आवश्यक कॉन्टेक्स्ट, डिफ़ॉल्ट 25-फ़ाइल थ्रेशोल्ड से अधिक ब्लास्ट रेडियस) पर सब्सट्रेट + को हार्ड ब्लॉक में बदलने के लिए `FORGE_ENFORCE=1` सेट करें। +- **डिफ़ॉल्ट रूप से मौन।** प्रति-कमांड `Forge — …` शीर्षक `--verbose` / + `FORGE_VERBOSE` के पीछे ब्रांडिंग क्रोम है; एक कमांड पहले अपना परिणाम देती है। +- **पाइप-अनुकूल आउटपुट।** पाइप किए जाने पर सादा पाठ; TTY पर यह ब्रांड-पैलेट रंग और + कॉन्फ़िडेंस मीटर जोड़ता है। `NO_COLOR` रंग बंद करता है, `FORCE_COLOR=1` उसे बलपूर्वक चालू करता है। +- **`--json`** स्क्रिप्टिंग के लिए सब्सट्रेट और अधिकांश एनालिसिस कमांड्स पर उपलब्ध है। + + + हमेशा-अद्यतन सूची के लिए `forge --help` चलाएँ, या हर टूल, क्रू, और गार्ड के एक-पंक्ति + कारण के साथ Start-Here इंडेक्स के लिए `forge catalog`। + + +## v0.19+ में नया + +कई कमांड्स और फ़्लैग v0.19 लाइन में आ रहे हैं। वे अपने समूह पृष्ठों पर प्रलेखित हैं +और इनलाइन फ़्लैग किए गए हैं: + +| कमांड / फ़्लैग | समूह | यह क्या करता है | +| ---------------------- | -------- | ----------------------------------------------- | +| `forge know` | Memory | किसी तथ्य को उसके सही स्टोरेज गंतव्य पर रूट करें। | +| `forge deja` | Memory | समान-पिछले-कार्य की खोज। | +| `forge precommit` | Quality | कमिट-स्तरीय सत्यापन गेट। | +| `forge radar` | Quality | निर्भरता-नवीनता रिंग्स। | +| `forge report` | Config | रेपो की Forge स्थिति की स्टैटिक HTML रिपोर्ट। | +| `forge tools` | Config | प्राथमिक-टूल चयन + gitignore वायरिंग। | +| `forge verify --deep` | Quality | मल्टी-लेंस सर्वसम्मति सत्यापन। | +| `forge update --to` | Core | किसी विशिष्ट संस्करण पर पिन या डाउनग्रेड करें। | diff --git a/mintlify/hi/cli/quality.mdx b/mintlify/hi/cli/quality.mdx new file mode 100644 index 0000000..b98b1d8 --- /dev/null +++ b/mintlify/hi/cli/quality.mdx @@ -0,0 +1,84 @@ +--- +title: "Quality कमांड्स" +description: "सत्यापन और सुरक्षा: verify, scan, spec, taste, uicheck, और harden — साथ ही v0.19+ precommit और radar गेट्स।" +--- + +Quality समूह सत्यापन और सुरक्षा सतह है। ये कैसे संयोजित होते हैं इसके लिए +[Verification gates](/hi/concepts/verification-gates) देखें। + +## `forge verify` + +स्वतंत्र सत्यापन गेट — टेस्ट्स + हैलुसिनेटेड-सिंबल + provenance। + +```bash +forge verify +forge verify --deep # multi-lens consensus (v0.19+) +``` + +## `forge scan` + +Skill-गेट — इंस्टॉल से पहले किसी skill या MCP सर्वर की injection / RCE / exfil के लिए जाँच करें। + +```bash +forge scan +``` + +## `forge spec` + +Spec-as-contract — init (OpenSpec), lock, और drift जाँचें। + +```bash +forge spec init +forge spec lock +forge spec check +``` + +## `forge taste` + +इस रेपो के लिए एक UI-taste टूल सक्षम करें (कोई arg नहीं होने पर विकल्प सूचीबद्ध होते हैं)। + +```bash +forge taste # list the profiles +forge taste # brutalist · corporate · editorial · minimalist · playful +``` + +`DESIGN.md` लिखता है और `uicheck design` गेट थ्रेशोल्ड्स को पैरामीटराइज़ करता है। + +## `forge uicheck` + +डिटरमिनिस्टिक UI जाँचें। + +```bash +forge uicheck contrast # WCAG contrast ratio +forge uicheck fingerprint # deterministic design fingerprint +forge uicheck design # slop-distance + conformance gate +forge uicheck visual # Playwright-rendered check (opt-in tier) +``` + +## `forge harden` + +सुरक्षा नियंत्रण वायर करें — gitleaks pre-commit + sandbox सेटिंग्स। + +```bash +forge harden +``` + +## `forge precommit` v0.19+ + +कमिट-स्तरीय गेट — कमिट समय पर सत्यापन-न्यूनतम चलाता है ताकि आंशिक या असत्यापित कार्य +उतरने से पहले पकड़ा जा सके। + +```bash +forge precommit +``` + +## `forge radar` v0.19+ + +निर्भरता-नवीनता रिंग्स — प्रोजेक्ट की निर्भरताओं को उनकी नवीनता के अनुसार समूहित करता है, +ताकि पुरानी या बहती निर्भरताएँ नुक़सान पहुँचाने से पहले सतह पर आ जाएँ। + +```bash +forge radar +``` + +रिंग्स कैसे पढ़ें इसके लिए [Keeping dependencies current](/hi/guides/radar-deps) गाइड देखें। diff --git a/mintlify/hi/cli/substrate.mdx b/mintlify/hi/cli/substrate.mdx new file mode 100644 index 0000000..130789a --- /dev/null +++ b/mintlify/hi/cli/substrate.mdx @@ -0,0 +1,103 @@ +--- +title: "Substrate कमांड्स" +description: "प्री-एक्शन गेट और उसके व्यक्तिगत रूप से कॉल किए जाने योग्य चरण: substrate, preflight, route, impact, scope, context, anchor, diagnose, imagine, और lean।" +--- + +Substrate समूह प्री-एक्शन गेट है। `forge substrate` बाकी को एक ही वर्डिक्ट में संयोजित +करता है; प्रत्येक चरण को अकेले भी कॉल किया जा सकता है। पाइपलाइन के लिए +[The pre-action gate](/hi/concepts/pre-action-gate) देखें। + +## `forge substrate` + +एक प्री-एक्शन गेट: अनुमान, रूट, प्रभाव, स्कोप, मेमोरी, वेरीफ़ाई। + +```bash +forge substrate "" +forge substrate "" --json +``` + +यदि यह `okToProceed:false` लौटाता है, तो एडिट करने से पहले लौटाए गए `assumption.questions` पूछें। + +## `forge preflight` + +अनुमान जाँच — कोई कार्य क्या नाम लेता है जो रेपो परिभाषित नहीं करता। + +```bash +forge preflight "" +``` + +## `forge route` + +किसी कार्य के लिए सबसे सस्ते समर्थ मॉडल की सिफ़ारिश करें। + +```bash +forge route "" +forge route gateway # emit LiteLLM gateway config +``` + +## `forge impact` + +atlas ग्राफ़ से किसी सिंबल या फ़ाइल के लिए ब्लास्ट रेडियस का पूर्वानुमान लगाएँ। + +```bash +forge impact +``` + +## `forge scope` + +फ़ाइलों को स्वतंत्र क्लस्टर्स में विघटित करें — साथ ही युग्मित फ़ाइलें जिनका नाम आपने नहीं लिया। + +```bash +forge scope +``` + +## `forge context` + +बजट-सीमित कॉन्टेक्स्ट संयोजन + पूर्णता गेट — किसी एडिट को क्या जानना ज़रूरी है। + +```bash +forge context "" +``` + +पूर्वानुमानित एडिट सेट पर set-cover के माध्यम से बजट-सीमित कॉन्टेक्स्ट संयोजित करता है, +एक कंप्रेशन लैडर लागू करता है, और गणना किए गए missing set की रिपोर्ट करता है। + +## `forge anchor` + +लक्ष्य-ड्रिफ्ट जाँच — क्या आपके वास्तविक (git) परिवर्तन अभी भी बताए गए लक्ष्य पर हैं? + +```bash +forge anchor set "" # persist the goal across sessions +forge anchor show +forge anchor clear +``` + +## `forge diagnose` + +डूम-लूप जाँच — एक असफलता दर्ज करें; वही हस्ताक्षर 3× एक निदान + एस्केलेशन बनाता है। + +```bash +forge diagnose "" +``` + +## `forge imagine` + +परिणाम सिमुलेशन — किसी कार्य के लिए पूर्वानुमानित ब्रेक्स + न्यूनतम ड्राई-रन टेस्ट सूट। + +```bash +forge imagine "" +forge imagine "" --run # execute the minimal suite sandboxed +``` + +## `forge lean` + +स्कोप-न्यूनता (M5) — डिफ़ के पदचिह्न को उस बनाम मापें जो कार्य ने माँगा था। + +```bash +forge lean +``` + + + `route`, `impact`, `scope`, `context`, `anchor`, और `lean` चरण सभी `forge substrate` + के अंदर चलते हैं। जब आपको केवल एक ही संकेत चाहिए तो उन्हें अलग-अलग कॉल करें। + diff --git a/mintlify/hi/concepts/config-compiler.mdx b/mintlify/hi/concepts/config-compiler.mdx new file mode 100644 index 0000000..ee9833b --- /dev/null +++ b/mintlify/hi/concepts/config-compiler.mdx @@ -0,0 +1,101 @@ +--- +title: "चार-परत कॉन्फ़िग कंपाइलर" +description: "सब्सट्रेट को एक बार लिखें; forge sync इसे प्रत्येक टूल के नेटिव कॉन्फ़िग में संकलित करता है। चार परतें बताती हैं कि दिमाग कैसे व्यक्त होता है; कंपाइलर बताता है कि यह कैसे डिलीवर होता है।" +--- + +आप सब्सट्रेट को एक बार लिखते हैं। `forge sync` उस स्रोत को प्रत्येक टूल के नेटिव कॉन्फ़िग में +संकलित करता है। चार परतें बताती हैं कि _दिमाग कैसे व्यक्त किया जाता है_; कंपाइलर बताता है +कि _यह कैसे डिलीवर होता है_। + +```mermaid +flowchart TD + S["source/ · rules.json · substrate.json · mcp.json"] -->|"forge sync — content-hash + DO-NOT-EDIT headers"| N["native configs · CLAUDE.md · AGENTS.md · .cursor · .gemini · .aider"] + S -. configures .-> L + subgraph L["the four layers"] + direction LR + T["tools · model-invoked skills"] + C["crew · isolated sub-agents"] + G["guards · deterministic hooks"] + M["mcp · atlas + substrate server"] + end +``` + +## एक स्रोत, कई एमिटर + +नियम **एक बार** लिखें (`source/rules.json`); एक डिटर्मिनिस्टिक कंपाइलर (`forge sync`) +प्रत्येक टूल के नेटिव फ़ॉर्मैट को कंटेंट-हैश हेडर के साथ एमिट करता है, जिससे ड्रिफ़्ट का +पता लगाया जा सकता है और पुनः चलाना no-op बन जाता है। कोई भी नियम कभी दो बार नहीं लिखा +जाता। कैनोनिकल स्रोत तीन फ़ाइलें हैं: + +| स्रोत फ़ाइल | इसमें क्या होता है | +| ----------------------- | -------------------------------------------------------------------- | +| `source/rules.json` | कैनोनिकल इंजीनियरिंग नियम (git, testing, security, style)। | +| `source/substrate.json` | Cognitive-substrate डिफ़ॉल्ट — थ्रेशोल्ड, रूटिंग, LLM नॉब्स। | +| `source/mcp.json` | MCP सर्वर परिभाषाएँ जो प्रत्येक टूल में एमिट होती हैं। | + +## चार परतें + +प्रत्येक परत ब्रांड-नामित है और क्रॉस-टूल एमिट होती है। + + + + `~/.forge/tools/` → `~/.claude/skills/`। मॉडल-इनवोक्ड स्किल्स, जो `SKILL.md` + मानक (`name` + `description` frontmatter) का पालन करती हैं। + + + `~/.forge/crew/` → `~/.claude/agents/`। पृथक-कॉन्टेक्स्ट सब-एजेंट जैसे कि scout, + verifier, और frontend-verifier। + + + `~/.forge/guards/` → `settings.json` हुक्स। **एकमात्र परत जो सुझाने के बजाय + _प्रवर्तन_ करती है।** एक guard एक डिटर्मिनिस्टिक हुक है जिससे मॉडल ड्रिफ़्ट नहीं कर + सकता। `CLAUDE.md` में प्रोज़ नियम स्वीकार किए जाते हैं और फिर कॉम्पैक्शन के बाद + भूल जाते हैं; एक guard ऐसा नहीं करता। हर प्रवर्तनीय invariant यहीं होना चाहिए। + + + Forge एक stdio सर्वर (`src/cortex_mcp.js`) शिप करता है जो 19 MCP टूल्स एक्सपोज़ + करता है: सब्सट्रेट चेक्स (`substrate_check` / `predict_impact` / + `assumption_gate` / …), मेमोरी रीड्स _और_ राइट्स (`forge_remember`, ledger + ratify/retract), और ops/health। + + + +क्रॉस-कटिंग चिंताएँ चारों में से गुज़रती हैं: **atlas** (कोड ग्राफ़), **lean** +(न्यूनतमवाद — एक टूल और एक Stop-guard दोनों के रूप में शिप होता है, ताकि यह लागू हो +चाहे मॉडल इसे इनवोक करे या नहीं), और **recall** (मेमोरी)। + +## प्रोज़ के ऊपर Guard + +जिन नियमों से मॉडल ड्रिफ़्ट कर सकता है वे प्रोज़ में रहते हैं; जिन्हें उसे **कभी नहीं** +तोड़ना चाहिए वे guards (डिटर्मिनिस्टिक शेल हुक्स) में रहते हैं। एक guard कॉन्टेक्स्ट +कॉम्पैक्शन के बाद भुलाया नहीं जा सकता। + + + हर प्रवर्तनीय invariant को `CLAUDE.md` से बाहर एक guard में ले जाएँ; प्रोज़ को पतला + रखें। Forge के डिज़ाइन में यह एकमात्र सबसे महत्वपूर्ण अनुशासन है। + + +## सत्यापित क्रॉस-टूल एमिट मैट्रिक्स + +Forge **नौ टूल्स** के लिए कॉन्फ़िग एमिट करता है, साथ ही Roo Code और VS Code के लिए एक +MCP सर्वर। प्रत्येक पंक्ति वेंडर डॉक्स के विरुद्ध पुष्टि की गई है। + +| टूल | नेटिव लक्ष्य | Forge कैसे एमिट करता है | +| ------------------ | ---------------------------------------------------------------- | --------------------------------------------------------------------- | +| **Claude Code** | `CLAUDE.md` (+ `.claude/rules/*.md`, `settings.json`) | पतला `CLAUDE.md` जिसकी पहली पंक्ति `@AGENTS.md` है; guards → settings | +| **Codex** | `AGENTS.md` नेटिव (32 KiB cap) | रूट पर कैनोनिकल `AGENTS.md` **ही** स्रोत है | +| **Cursor** | `AGENTS.md` + `.cursor/rules/*.mdc` | फ़्लैट नियमों के लिए `AGENTS.md`; स्कोपिंग आवश्यक होने पर `.mdc` | +| **Gemini** | `GEMINI.md`, या `context.fileName` opt-in के ज़रिए `AGENTS.md` | दूसरी कॉपी टालने के लिए `.gemini/settings.json` लिखता है | +| **Aider** | `.aider.conf.yml` में `read:` के ज़रिए `CONVENTIONS.md` | `read: AGENTS.md` के साथ `.aider.conf.yml` एमिट करता है | +| **Copilot** | रूट `AGENTS.md` + `.github/copilot-instructions.md` | रूट `AGENTS.md` पर निर्भर करता है; वैकल्पिक `.github` पॉइंटर | +| **Windsurf/Devin** | `AGENTS.md` ऑटो-डिस्कवर (caps 6k/12k chars) | caps के अंतर्गत रूट `AGENTS.md`; `.windsurf` बनाम `.devin` पहचानता है | +| **Zed** | प्रीसिडेंस सूची का पहला मैच जिसमें `AGENTS.md` शामिल है | `AGENTS.md` एमिट करता है; doctor किसी भी shadowing legacy फ़ाइल को फ़्लैग करता है | +| **Continue** | `.continue/rules/*.md` + `.continue/mcpServers/*.yaml` | एक नियम फ़ाइल और Forge MCP सर्वर कॉन्फ़िग एमिट करता है | + +Roo Code और VS Code को Forge MCP सर्वर `forge init` के ज़रिए मिलता है (`.roo/mcp.json`, +`.vscode/mcp.json`) न कि किसी नियम फ़ाइल के ज़रिए। + + + **Char caps वास्तविक हैं।** Codex 32 KiB पर, Windsurf 6k/12k पर ट्रंकेट करता है। + `forge sync` एक स्रोत आकार बजट लागू करता है ताकि कोई कॉन्फ़िग कभी चुपचाप ट्रंकेट न हो। + diff --git a/mintlify/hi/concepts/cross-session-memory.mdx b/mintlify/hi/concepts/cross-session-memory.mdx new file mode 100644 index 0000000..a5ebbf1 --- /dev/null +++ b/mintlify/hi/concepts/cross-session-memory.mdx @@ -0,0 +1,88 @@ +--- +title: "क्रॉस-सेशन मेमोरी" +description: "सेशन एंकरिंग, कम्प्लीशन गेट, हैंडऑफ़ स्नैपशॉट, और डिसीज़न लॉग — वह परत जो सेशन एम्नेसिया और आंशिक कार्य को खत्म करती है।" +--- + +यह परत जिन दो विफलता मोड्स को खत्म करने के लिए है: **आंशिक कार्य** (कोड बदलाव उन artifacts +के बिना जो उस पर निर्भर हैं) और **सेशन एम्नेसिया** (अगला सेशन उस बात को फिर से मान लेता है +जो इस सेशन को पता थी)। निर्देश सही व्यवहार की _संभावना_ बढ़ाते हैं; डिटर्मिनिस्टिक हुक्स +एक _न्यूनतम स्तर_ की गारंटी देते हैं। + +## सेशन एंकरिंग + +`SessionStart` पर (`src/session.js`), Forge प्रति सेशन एक बार `HEAD` रिकॉर्ड करता है, +सप्ताह-पुराने सेशन artifacts को छाँटता है, और एक ताज़ा ओरिएंटेशन इंजेक्ट करता है: + + + + पिछले सुधारों से खनन किए गए Cortex पाठ। + + + घोषित लक्ष्य, ताकि ड्रिफ़्ट को उसके विरुद्ध मापा जा सके। + + + सीमित `.forge/state.md` जो पिछले सेशन ने लिखा था। + + + हाल के कमिट्स और uncommitted बदलाव — प्रमाण, प्राथमिकताएँ नहीं। + + + +एक ताज़ा सेशन प्राथमिकताओं पर नहीं, प्रमाण पर ओरिएंट होता है। + +## कम्प्लीशन गेट + +केवल एक Stop-path guard जवाब दे सकता है वह है `completion-gate.sh` +(`src/gate.js`)। यह सिंक्रोनसली चलता है; पाठ-खनन `cortex.sh stop` डिटैच्ड रहता है +और कभी ब्लॉक नहीं कर सकता। + +बदला हुआ सेट **सेशन-स्कोप्ड** है: उन कमिट्स की फ़ाइलें जिनका committer समय सेशन शुरू होने +पर या उसके बाद है, साथ ही working-tree बदलाव माइनस वह गंदगी जो `SessionStart` पर +स्नैपशॉट की गई थी — इसलिए पहले से मौजूद संपादन, ब्रांच स्विच, और `git pull` कभी एजेंट पर +नहीं थोपे जाते। + + + यदि कोड बदला और उसके साथ कोई doc या state artifact नहीं आया, तो gate **एक बार ब्लॉक करता है** + एक repair checklist को कारण के रूप में देते हुए। बाकी हर मामले में यह allow करता है, और + हर आंतरिक त्रुटि allow करती है (fail-open)। `FORGE_STOPGATE=0` इसे अक्षम करता है। + + +Repair checklist उन टूल्स की ओर इशारा करता है जो काम पूरा करते हैं: + +```bash +forge docs sync # sweep the diff for stale doc mentions +forge handoff "" --next "" # write the bounded session snapshot +forge decide " — " # record a choice so no session re-decides it +``` + +## हैंडऑफ़ और निर्णय + +दो स्टोर्स सेशनों में ज्ञान बनाए रखते हैं: + +| स्टोर | सिमैंटिक्स | +| ------------------- | ------------------------------------------------------------------------------------ | +| `.forge/state.md` | एक सीमित **rewrite** (स्नैपशॉट) — लोडर लागत हमेशा `O(bound)` रहती है। | +| `.forge/decisions.md` | Append-only **ADR-lite** (`D-####`) जिसके साथ एक machine-readable decision ledger twin है। | + +दोनों write पर secrets को अस्वीकार करते हैं। `state.md` हर सेशन शुरू होने पर पुनः इंजेक्ट होता है; +`decisions.md` को पहले पढ़ा जाता है, इससे पहले कि कुछ ऐसा फिर से तय किया जाए जो पिछले सेशन +ने तय किया था। + +```bash +forge handoff "" --next "" +forge decide " — " +forge decide # read the log before re-deciding +``` + +## Diff-आधारित docs sweep + +`forge docs sync` diff-आकार वाले प्रश्न का उत्तर देता है: बदले गए identifiers (paths, +definitions, और called symbols, जोड़ी गई _और_ हटाई गई लाइनों से) प्रत्येक doc artifact +के विरुद्ध swept → UPDATED / STALE (file:line hits के साथ) / VERIFIED-UNAFFECTED, कारण +रिकॉर्ड होने के साथ। यह एक शुद्ध रिपोर्टर है; कम्प्लीशन गेट दाँत प्रदान करता है। + + + `recall` और `cortex` केवल file-and-prompt मेमोरी हैं — **weight-level** learning **नहीं**। + Consolidation एक summarizer है जो hallucinate कर सकता है, इसलिए यह advisory, + मानव-समीक्षा-योग्य, और secret-free बना रहता है। + diff --git a/mintlify/hi/concepts/model-routing.mdx b/mintlify/hi/concepts/model-routing.mdx new file mode 100644 index 0000000..776f240 --- /dev/null +++ b/mintlify/hi/concepts/model-routing.mdx @@ -0,0 +1,80 @@ +--- +title: "मॉडल रूटिंग" +description: "एक डिटर्मिनिस्टिक, diffable रुब्रिक डिस्पैच से पहले सबसे सस्ता सक्षम मॉडल टियर चुनता है — self-hosted gateways के लिए एक fail-safe remap के साथ।" +--- + +Forge किसी कार्य के लिए सबसे सस्ते सक्षम मॉडल की सिफ़ारिश डिस्पैच से **पहले** करता है, एक +डिटर्मिनिस्टिक रुब्रिक से जिसे आप repo में पढ़ सकते हैं (`src/model_tiers.json`)। एक gateway +जो रिक्वेस्ट समय पर proxy के अंदर निर्णय लेता है, उसके विपरीत, रूटिंग निर्णय git में +दृश्यमान और diffable है। + +## एक टियर की सिफ़ारिश करें — `forge route` + +```bash +forge route "" # cheapest capable model tier for the task +forge route gateway # emit LiteLLM gateway config +``` + +सिफ़ारिश एक लेबल्ड बैंक (English + Hinglish rows) के ऊपर exemplar k-NN गणित है, जो +overlap-similarity मेट्रिक और एक confidence gate के तहत की जाती है — keyword lookup नहीं। + + + अनुशंसित `route.tier` पर शुरू करें और केवल एक बाहरी verifier के विफल होने के बाद escalate + करें, कभी preemptively नहीं। इससे जब कार्य को वास्तव में क्षमता की ज़रूरत होती है तब + क्षमता सीमित किए बिना खर्च कम रहता है। + + +## पहले Intent, फिर टियर + +रूटिंग अपनी गणित को intent detection (`src/intent.js`) के साथ साझा करती है: एक prompt +उसी exemplar k-NN estimator द्वारा एक intent में मैप होता है। ध्यान दें कि दोनों अलग-अलग +stop-sets का उपयोग करते हैं — route सामान्य verbs (`fix` / `add` / `build`) को complexity +noise मानती है, लेकिन वही verbs intent signal होते हैं। + +## टियर तालिका + +टियर तालिका (`src/model_tiers.json`) परिवार (haiku / sonnet / opus / fable) के अनुसार +सार्वजनिक Anthropic मॉडल IDs को पिन करती है। Doc कीमतें docs check द्वारा इस फ़ाइल के +विरुद्ध reconciled होती हैं, इसलिए prose और तालिका ड्रिफ़्ट नहीं कर सकते। + +## Self-hosted gateway remap + +एक self-hosted LiteLLM या proxy gateway अपने खुद के मॉडल नाम देता है, इसलिए एक stock ID +सीधे भेजने पर 404 आएगा। जब एक non-default gateway base URL कॉन्फ़िगर होता है, तो Forge +(`src/gateway_model_map.js`) `GET /v1/models` को **प्रति process एक बार** fetch करता है +और प्रत्येक विज्ञापित id को हर टियर के family के विरुद्ध score करता है: + + + + Family शब्द (haiku / sonnet / opus / fable) मैच होना चाहिए — यह एक hard gate है। + + + Family के भीतर, टियर के नाम टोकनों का `setOverlap` गुणांक सर्वश्रेष्ठ मैच चुनता है। + + + Ties canonical नाम के सबसे करीब id की ओर टूटते हैं। + + + + + Remap gateway से **केवल** तब परामर्श करता है जब resolved id एक _stock_ ID हो — एक स्पष्ट + `.forge/providers.json` alias या एक `ANTHROPIC_MODEL` override को कभी नहीं छुआ जाता। यह + no gateway, unreachable `/v1/models`, या no family match पर stock ID पर fail-safe रहता है, + ताकि सीधे `api.anthropic.com` उपयोगकर्ता byte-identical रहें। + + +`forge doctor` की **gateway models** पंक्ति सत्यापन के लिए resolved `tier → model` मैपिंग +प्रिंट करती है। + +## Providers और लागत + +```bash +forge config # show / switch / add providers, set the default model +forge cost # real per-day spend +forge cost --stages # measured per-stage cost factors +``` + + + `forge cost --stages` **केवल मापे गए stages** रिपोर्ट करता है — बिना events वाला stage + "no data" कहता है, कभी default नहीं। एक संख्या तब तक धारणा है जब तक मापी न जाए। + diff --git a/mintlify/hi/concepts/pre-action-gate.mdx b/mintlify/hi/concepts/pre-action-gate.mdx new file mode 100644 index 0000000..abe3341 --- /dev/null +++ b/mintlify/hi/concepts/pre-action-gate.mdx @@ -0,0 +1,100 @@ +--- +title: "प्री-एक्शन गेट" +description: "forge substrate मॉडल के कोड संपादित करने से पहले एक क्रमबद्ध चेक पास चलाता है और एक ही verdict देता है — assumptions, routing, impact, scope, memory, और verification।" +--- + +**Cognitive substrate** — वह परत जो मॉडल के कोड संपादित करने से _पहले_ चलती है। `forge +substrate ""` (और MCP टूल `substrate_check`) एक क्रमबद्ध पास चलाता है और एक ही +verdict देता है। यह अलग-अलग कॉल किए जा सकने वाले चरणों — `preflight`, `route`, `atlas`, +`impact`, `reuse`, `context`, `scope`, `lean`, `anchor`, `verify` — को एक pre-action +अनुबंध में मिलाता है। + +```mermaid +flowchart TD + RE["referenced entities"] --> INTAKE + subgraph INTAKE["intake"] + direction LR + PF["preflight · assumption gap"] --> RT["route · cheapest tier"] + end + INTAKE --> ANALYSIS + subgraph ANALYSIS["analysis"] + direction LR + AT["atlas · code graph"] --> IM["impact · blast radius"] --> PT["predict · failing tests"] --> RU["reuse · cache hit?"] + end + ANALYSIS --> SAFETY + subgraph SAFETY["safety + fit"] + direction LR + CX["context · completeness gate"] --> SC["scope · coupled files"] --> ME["memory · recall + lessons"] --> MN["minimality · lean footprint"] --> GA["goal-anchor · drift check"] + end + SAFETY --> VD["verdict"] +``` + +## तीन चरण + + + + **preflight** assumption gap ढूँढ़ता है — कार्य क्या नाम लेता है जिसे repo परिभाषित + नहीं करता। **route** सबसे सस्ता सक्षम मॉडल टियर चुनता है। + + + **atlas** कोड ग्राफ़ पढ़ता है, **impact** blast radius की गणना करता है, **predict** + उन tests के नाम बताता है जिनके विफल होने की संभावना है, और **reuse** एक सत्यापित + cache hit की जाँच करता है। + + + **context** completeness gate चलाता है, **scope** coupled फ़ाइलें सामने लाता है, + **memory** recall + lessons इंजेक्ट करता है, **minimality** lean footprint मापता है, + और **goal-anchor** drift की जाँच करता है। + + + +## Blast radius + +**Blast radius** — फ़ाइलों का वह सेट जिस पर एक edit के प्रभाव की भविष्यवाणी की जाती है, +कोड ग्राफ़ से पढ़ा गया। `forge impact` इसकी गणना करता है; पाइपलाइन मॉडल के कुछ छूने से +पहले इसे सामने लाती है। + +```bash +forge impact verifyToken # predicted impacted files for a symbol +forge impact src/auth.js # …or for a file +``` + +## डिफ़ॉल्ट रूप से Advisory + +Verdict **डिफ़ॉल्ट रूप से advisory** है — यह रिपोर्ट करता है, ब्लॉक नहीं करता। सबसे मज़बूत +संकेतों को hard block में बदलने के लिए `FORGE_ENFORCE=1` सेट करें: + + + + preflight को कोई actionable intent नहीं मिलता — एक underspecified task। + + + completeness gate predicted edit set को cover नहीं कर सकता। + + + impacted set डिफ़ॉल्ट ~25-file threshold से अधिक है। + + + +बाकी सब कुछ एक warning बनी रहती है जिसे मानव override कर सकता है। + + + Claude Code पर पूरा गेट **हर prompt पर स्वचालित रूप से** एक `UserPromptSubmit` hook के + ज़रिए चलता है — clean tasks पर silent। `forge substrate "" --json` + scripting के लिए machine-readable verdict देता है। + + +## इसे चलाना + +```bash +forge substrate "Change verifyToken in src/auth.js to require length > 20; update tests" +forge substrate "" --json +``` + +यदि verdict `ASK FIRST` है, तो संपादित करने से पहले लौटाए गए `assumption.questions` +पूछें — एक under-specified task का अनुमान न लगाएँ। अनुशंसित `route.tier` पर शुरू करें और +केवल एक बाहरी verifier के विफल होने के बाद escalate करें, कभी preemptively नहीं। + + + मेमोरी stage proof-carrying ledger से पढ़ता है। + diff --git a/mintlify/hi/concepts/proof-carrying-memory.mdx b/mintlify/hi/concepts/proof-carrying-memory.mdx new file mode 100644 index 0000000..741dc07 --- /dev/null +++ b/mintlify/hi/concepts/proof-carrying-memory.mdx @@ -0,0 +1,115 @@ +--- +title: "Proof-carrying memory" +description: "प्रत्येक संग्रहीत तथ्य, पाठ, या reuse artifact एक claim है जो अपने साथ अपना प्रमाण रखता है — जिस पर तभी भरोसा किया जाता है जब स्वतंत्र oracles उसका confidence एक floor से ऊपर उठा दें।" +--- + +**Proof-carrying memory (PCM)** — प्रत्येक संग्रहीत तथ्य, पाठ, या reuse artifact एक +_claim_ है जो अपने साथ अपना प्रमाण रखता है। इस पर तभी भरोसा किया जाता है जब स्वतंत्र +oracles (tests, CI, एक मानव accept/revert) इसका confidence एक floor से ऊपर उठा दें। +एक ग़लत पाठ ossify होने के बजाय decay होकर बाहर हो जाता है। + + + "Proof-carrying memory" हमारा नाम है **evidence-referenced, content-addressed + memory** के लिए — एक claim जिसे उसके content के hash द्वारा address किया जाता है और + उसे उन oracle outcomes से जोड़ा जाता है जो उसका समर्थन करते हैं। "Proof" वह evidence + trail और confidence नियम है, **किसी formal machine-checked proof के तौर पर नहीं**; loop + में कोई theorem prover नहीं है। + + +## एक store, कई writers + +सभी memory subsystems एक ही store पर converge होते हैं। `recall`, `remember`/`brain`, +`cortex` lessons, `reuse` artifacts, और doom-loop `diagnose` results सभी +content-addressed claims को `.forge/ledger/` में लिखते हैं। + +```mermaid +flowchart LR + subgraph EV["local events"] + direction TB + E1["recall / remember"] + E2["cortex lesson"] + E3["reuse mint"] + E4["diagnose"] + end + EV -->|"content-addressed claims"| LG["(.forge/ledger)"] + O["independent oracles · tests · CI · human accept/revert"] -->|"append evidence · move confidence"| LG + TM["teammate ledgers"] <-->|"git union-merge · conflict-free"| LG + LG --> RV["merged read view · recall list · lesson inject · brain index"] +``` + +## यह conflicts के बिना क्यों converge होता है + +क्योंकि एक claim के bytes `(kind, body, scope)` का शुद्ध function हैं, हर replica एक ही +identity कंप्यूट करता है — इसलिए teammate ledgers plain git पर बिना conflicts के आपस +में fold हो जाते हैं। + +यांत्रिक रूप से: + +- **Evidence और tombstones append-only**, hash-deduped logs हैं। +- **Confidence (`val`)** एक decayed Beta posterior है, जिसे केवल oracles ही हिलाते हैं। +- **Merge एक join-semilattice है** — property-tested कि यह commutative, associative, + और idempotent है — इसलिए ledgers किसी भी क्रम में converge हो जाते हैं। + + + `forge init` union-merge `.gitattributes` नियम emit करता है जो ledger को चाहिए; + `forge ledger merge ` किसी अन्य ledger tree को fold कर लेता है। पूरा निर्णय + ADR-0006 (proof-carrying memory) में दर्ज है। + + +## Oracles ही confidence हिलाते हैं — कुछ और नहीं + +केवल स्वतंत्र oracles एक memory का confidence हिला सकते हैं: + + + + एक passing test जो claim को exercise करता है, उसका confidence बढ़ाता है। + + + एक green pipeline स्वतंत्र evidence है कि claim अभी भी टिकी हुई है। + + + एक explicit accept या एक revert सबसे मज़बूत signal है। + + + +Unverifiable evidence को एक closed `ORACLES` table (`src/ledger.js`) द्वारा अस्वीकार +कर दिया जाता है। असमीक्षित knowledge deletion की ओर नहीं, _uncertainty_ की ओर decay +होता है — निष्क्रिय claims audit के लिए रखे जाते हैं, कभी चुपचाप हटाए नहीं जाते। + +## Ledger surface + +```bash +forge ledger stats # what the repo knows, by kind and trust level +forge ledger verify # re-check claims are in normal form +forge ledger show # a claim and its evidence trail +forge ledger blame # who minted it, every oracle outcome, per-author trust +forge ledger query "" # retrieve claims by relevance +forge ledger ratify # human accept +forge ledger retract # tombstone a claim +forge ledger merge # fold a teammate's ledger in, conflict-free +forge ledger import # bridge legacy stores into the ledger +``` + +Per-user ledger के लिए `--personal` जोड़ें। + +## Reuse cache भी proof-carrying है + +`forge reuse` एक proof-carrying code cache है। एक generated artifact तभी दोबारा serve +होता है जब उसका evidence अभी भी टिका हो — confidence floor से ऊपर हो **और** उसके atlas +dependencies अभी भी resolve हों। अन्यथा यह generation पर fall through करता है और वापसी +पर एक fresh claim mint करता है। + +```mermaid +flowchart LR + SP["spec"] --> FP["fingerprint · MinHash + LSH"] + FP --> LD["match ladder · exact to near to adapt to miss"] + LD --> GT{"confidence >= floor AND deps resolve?"} + GT -->|"yes"| SV["serve · proof holds"] + GT -->|"miss"| GN["generate"] + GN -->|"mint claim"| MT["(.forge/ledger)"] +``` + + + MinHash near-match बहुत छोटे specs पर कमज़ोर है। एक वैकल्पिक embeddings backend + (`FORGE_EMBED`) इसे बेहतर बनाता है; MinHash zero-dependency डिफ़ॉल्ट बना रहता है। + diff --git a/mintlify/hi/concepts/verification-gates.mdx b/mintlify/hi/concepts/verification-gates.mdx new file mode 100644 index 0000000..bfc786b --- /dev/null +++ b/mintlify/hi/concepts/verification-gates.mdx @@ -0,0 +1,101 @@ +--- +title: "Verification gates" +description: "स्वतंत्र सत्यापन, hallucinated-symbol flag, spec-as-contract, और skill-gate — ऐसे चेक्स जिन्हें आप चला सकते हैं जो सटीकता को घटाते हैं, पर कभी प्रमाणित नहीं करते।" +--- + +कोई भी काम तब तक "पूरा" नहीं है जब तक आप एक ऐसा चेक न चला सकें — एक test, एक build exit +code, एक screenshot। Forge के verification gates प्रत्येक एक और catch जोड़ते हैं। +प्रति-task miss rate `1 − p` और gate catch rate `c` के साथ, silent misses `(1 − p)(1 − c)` +तक गिर जाते हैं, और यहाँ हर gate एक और `c` है। + + + **Verification घटाता है, प्रमाणित नहीं करता।** Crew verifiers और hallucinated-symbol + flag review burden कम करते हैं; वे कोड को सही साबित नहीं करते। Tests और मानव सुधार + हमेशा जीतते हैं। + + +## स्वतंत्र सत्यापन — `forge verify` + +एक स्वतंत्र gate: यह repo के वास्तविक tests चलाता है, hallucinated symbols flag करता है, और +provenance जाँचता है। + +```bash +forge verify # tests + hallucinated-symbol + provenance +forge verify --deep # multi-lens consensus — several independent checks must agree +``` + + + `--deep` (v0.19+) एक multi-lens consensus तक escalate करता है: बदलाव को कई स्वतंत्र + verification lenses से गुज़रना पड़ता है, केवल एक से नहीं। + + +## Hallucinated-symbol flag — `forge atlas has` + +`forge atlas has ` hallucination check है: यदि मॉडल किसी ऐसे symbol को call +करता है जो code graph में नहीं है, तो gate उसे flag करता है। + +```bash +forge atlas build # index this repo's symbols → .forge/atlas.json +forge atlas has useAuth # "not found" = likely hallucinated +``` + +Atlas जानबूझकर plain JSON है — Codex, Cursor, Gemini, और Aider `.forge/atlas.json` +को CLI या plain `jq` के ज़रिए पढ़ते हैं, बिना किसी MCP dependency के। + +## Spec-as-contract — `forge spec` + +व्यवहार को एक spec से pin करें और उससे drift पहचानें: + +```bash +forge spec init # scaffold an OpenSpec contract +forge spec lock # lock the current spec as the contract +forge spec check # report drift against the locked contract +``` + +## Skill-gate — `forge scan` + +किसी skill या MCP server को install करने से पहले, उसे injection, RCE, या exfiltration +के लिए जाँचें: + +```bash +forge scan +``` + + + Clean scan **safety certification नहीं है।** Built-in heuristic केवल known attack + shapes (critical) और कुछ high-severity patterns को पकड़ता है; pass का मतलब है _"कोई + critical signature नहीं मिला"_, _"install करने के लिए सुरक्षित"_ नहीं। हमेशा source, + permissions, package provenance, और network behaviour ख़ुद review करें। एक + **high**-severity finding को safe के रूप में मार्क नहीं किया जाता, भले ही यह hard-block + न करे। External scanner opt-in है और जब तक आप उसे enable न करें, कोई network call + नहीं करता। + + +## Hardening — `forge harden` + +Secrets और unsafe changes को बाहर रखने वाले security controls को wire करें: + +```bash +forge harden # gitleaks pre-commit + sandbox settings +``` + +## Commit-level gate — `forge precommit` + + + `forge precommit` (v0.19+) एक commit-level gate है — यह commit time पर verification + floor चलाता है ताकि आंशिक या unverified काम land होने से पहले पकड़ा जाए। + + +## UI checks — `forge uicheck` + +Deterministic UI checks, पहले तीन lenses के लिए कोई LLM नहीं और कोई screenshots नहीं: + +```bash +forge uicheck contrast # WCAG contrast ratio +forge uicheck fingerprint # deterministic design fingerprint +forge uicheck design # slop-distance + conformance gate +forge uicheck visual # Playwright-rendered check (opt-in tier) +``` + +इसे `forge taste` के साथ जोड़ें ताकि एक visual direction चुनें (brutalist, corporate, +editorial, minimalist, playful) और `design` gate की thresholds को parameterize करें। diff --git a/mintlify/hi/guides/radar-deps.mdx b/mintlify/hi/guides/radar-deps.mdx new file mode 100644 index 0000000..0fdce28 --- /dev/null +++ b/mintlify/hi/guides/radar-deps.mdx @@ -0,0 +1,69 @@ +--- +title: "radar के साथ dependencies को current रखना" +description: "forge radar आपकी dependencies को currency rings में समूहित करता है ताकि stale या drifting dependencies तंग करने से पहले सामने आ जाएँ।" +--- + + + `forge radar` v0.19 लाइन में आ रहा है। यह गाइड बताता है कि यह मौजूदा dependency-currency + discipline में कैसे फ़िट होता है; अपने installed version में उपलब्धता की पुष्टि करने के लिए + `forge --help` चलाएँ। + + +Forge के इंजीनियरिंग नियमों में से एक है: _dependency जोड़ने से पहले, live sources से +वर्तमान सर्वोत्तम विकल्प की पुष्टि करें, और वही पसंद करें जो प्रोजेक्ट पहले से उपयोग कर रहा है।_ +`forge radar` आपकी dependencies की standing state दिखाता है ताकि उस नियम के पीछे data हो। + +## विचार: currency rings + +`forge radar` प्रोजेक्ट की dependencies को concentric **currency rings** में समूहित करता है +इस आधार पर कि प्रत्येक कितना current है — केंद्र में up-to-date से लेकर किनारे पर stale +या drifting तक। Rings पढ़ना "हमने क्या drift होने दिया है?" का उत्तर देने का तेज़ तरीका है, +बिना हर package को हाथ से audit किए। + +```bash +forge radar +``` + +## Dependency सूची कहाँ से आती है + +Radar उसी manifest reading पर बनता है जो `forge stack` को शक्ति देती है, जो repo की +वास्तविक stack को उसके dependency manifests से पहचानती है: + +```bash +forge stack # languages, frameworks, package managers, real test commands +``` + +क्योंकि detection data-driven और ecosystems (`package.json`, `pyproject.toml`, `go.mod`, +`Cargo.toml`, `Gemfile`, `composer.json`, `pom.xml` / `build.gradle`, `*.csproj`) के +पार fail-safe है, radar उन्हीं manifests के set के लिए currency के बारे में तर्क कर सकता +है जिन्हें `stack` समझता है। + +## Loop में इसका उपयोग + + + + यह देखने के लिए `forge radar` चलाएँ कि कौन-सी dependencies पहले से drift हो रही हैं, + इससे पहले कि आप कोई जोड़ें या bump करें। + + + यदि कोई सक्षम, current dependency पहले से एक inner ring में है, तो नई जोड़ने के + बजाय उसका reuse करें — सबसे छोटा बदलाव जो फ़िट होता है, जीतता है। + + + जब आप किसी dependency को bump या replace करें, तो कारण दर्ज करें: + ```bash + forge decide "bump to — " + ``` + ताकि भविष्य का सेशन इस choice को दोबारा litigate करने के बजाय पढ़े। + + + + + Radar currency रिपोर्ट करता है; आपके लिए upgrade नहीं करता। इसके rings को एक मानव + निर्णय के लिए advisory input की तरह मानें — और किसी भी bump की repo के वास्तविक tests + (`forge verify`) के साथ पुष्टि करें, तभी उसे done कहें। + + + + Dependency bump के बाद, Quality gates चलाएँ — `forge verify` और `forge precommit`। + diff --git a/mintlify/hi/guides/team-memory.mdx b/mintlify/hi/guides/team-memory.mdx new file mode 100644 index 0000000..ee2676b --- /dev/null +++ b/mintlify/hi/guides/team-memory.mdx @@ -0,0 +1,80 @@ +--- +title: "Ledger के साथ टीम मेमोरी" +description: "किसी टीममेट के ledger को plain git पर, conflict-free, fold करें — कोई server नहीं, कोई sync service नहीं, बस files जो किसी भी क्रम में converge होती हैं।" +--- + +Substrate जो कुछ भी सीखता है — cortex lessons, `forge remember` facts, verified reuse +artifacts — वह content-addressed claims के रूप में एक git-native ledger +(`.forge/ledger/`) में land होता है, जो बिना conflicts के merge करने के लिए बनाया गया +है। कोई server नहीं और कोई sync service नहीं; यह बस git में files हैं। + +## तीन commands में team memory + + + + ```bash + forge init + ``` + अन्य बातों के साथ यह `.gitattributes` union-merge नियम emit करता है जो ledger को चाहिए। + + + Cortex lessons और `forge remember` facts आपके काम करते-करते claims को ledger में + shadow करते हैं — अलग से कुछ चलाने की ज़रूरत नहीं। + + + ```bash + git pull && forge ledger merge + ``` + किसी भी क्रम में — merge conflict-free है। + + + +## यह conflict क्यों नहीं कर सकता + +एक claim के bytes `(kind, body, scope)` का शुद्ध function हैं, इसलिए हर replica एक ही +knowledge के लिए एक ही identity कंप्यूट करता है। Merge एक join-semilattice है — +property-tested कि यह commutative, associative, और idempotent है — इसलिए दो टीममेट्स +के ledgers उसी state पर converge होते हैं, चाहे पहले कौन sync करे। + +```mermaid +flowchart LR + A["your ledger"] <-->|"git union-merge · conflict-free"| B["teammate ledger"] + A --> M["merged read view"] + B --> M + M --> R["recall list · lesson inject · brain index"] +``` + + + स्वतंत्र रूप से mint की गई identical knowledge **एक** claim पर converge होती है, जिसकी + provenance में हर author संरक्षित रहता है। + + +## Trust और provenance + +Confidence केवल स्वतंत्र oracles द्वारा हिलाया जाता है — tests, CI, एक मानव accept/revert — +इसलिए किसी टीममेट के ledger को import करना उनके नोट्स पर आँख मूँदकर भरोसा नहीं करता; यह +उनका _evidence_ import करता है। + +```bash +forge ledger blame # who minted a claim, every oracle outcome, per-author trust +forge ledger stats # the merged view, by kind and trust level +forge ledger verify # confirm every claim is in normal form +``` + +## टीम में Reuse + +एक बार किसी टीममेट का verified कोड merged ledger में आ जाए, तो आप उसे उसके proof के साथ +reuse कर सकते हैं: + +```bash +forge reuse query "" +``` + +एक hit working, test-confirmed कोड की ओर इशारा करता है और `forge ledger blame` जो उसे +साबित करता है — इसे regenerate करने के बजाय reuse करें। + + + निष्क्रिय claims audit के लिए रखे जाते हैं, कभी हटाए नहीं जाते; असमीक्षित knowledge + deletion की ओर नहीं, _uncertainty_ की ओर decay होती है। Ledger एक evidence trail है, + कोई cache नहीं जिसे आप चुपचाप खो सकें। + diff --git a/mintlify/hi/guides/zero-config-onboarding.mdx b/mintlify/hi/guides/zero-config-onboarding.mdx new file mode 100644 index 0000000..e4597a6 --- /dev/null +++ b/mintlify/hi/guides/zero-config-onboarding.mdx @@ -0,0 +1,88 @@ +--- +title: "मार्गदर्शित, कम-कॉन्फ़िगरेशन Onboarding" +description: "पाँच मिनट में उत्पादक: एक बार install करें, एक repo को एक बार configure करें, एक task करें, और दूसरे दिन ledger का फ़ायदा मिलना शुरू करें — मार्गदर्शित, कम-कॉन्फ़िगरेशन, zero-touch नहीं।" +--- + +Forge का लक्ष्य है **मार्गदर्शित, कम-कॉन्फ़िगरेशन onboarding** — एक नया repo आमतौर पर लगभग +पाँच मिनट में उत्पादक हो जाता है। एक बार install करें, एक repo को एक बार configure करें, +एक task करें, और दूसरे दिन ledger का फ़ायदा मिलना शुरू हो जाता है। (यह low-configuration +है, zero-configuration नहीं: आप अभी भी CLI install करते हैं, हर repo में `forge init` +चलाते हैं, और कुछ paths Bash, Git, और `jq` मानते हैं।) + +```mermaid +flowchart TD + I["forge init"] --> Cfg["every tool configured from one source"] + Cfg --> Work["you work as usual"] + Work --> Gate["substrate checks each task · ask first? · which model? · what breaks?"] + Gate --> Edit["agent edits, with guardrails"] + Edit --> Learn["cortex learns from corrections"] + Learn -.->|next task is smarter| Work +``` + +## 1. Install (एक बार) + +अनुशंसित paths को किसी token या clone की ज़रूरत नहीं: + + + +```bash Plugin +/plugin marketplace add CodeWithJuber/forgekit +/plugin install forgekit +``` + +```bash CLI +npm install -g @codewithjuber/forgekit +``` + + + +```bash +forge doctor # everything green? +``` + +## 2. एक repo configure करें (प्रति repo एक बार) + +```bash +cd ~/your-project +forge init # emits AGENTS.md, CLAUDE.md, .gemini/settings.json, .aider.conf.yml … +``` + +अब Claude Code, Codex, Cursor, Gemini, Aider, Copilot, Windsurf, Zed, और Continue सभी +**एक ही** नियम पढ़ते हैं — हर एक अपनी native फ़ाइल से। बाद में एक नियम बदलने के लिए +`source/rules.json` संपादित करें (या प्रति-repo `.forge/rules.json` छोड़ें), फिर +`forge sync` चलाएँ। + +## 3. Cognitive substrate का उपयोग करें + +```bash +forge substrate "" # ask/route/impact/scope/reuse/context/memory/verify in one pass +forge substrate "" --json +forge impact # the blast radius on its own +``` + +यदि `forge substrate` कहता है `ASK FIRST`, तो संपादित करने से पहले लौटाए गए प्रश्न पूछें। + +## 4. Extras का उपयोग करें + +```bash +forge atlas build # index this repo's symbols → .forge/atlas.json +forge atlas query useAuth # where is it defined? +forge atlas has useAuth # does it exist? "not found" = likely hallucinated +forge recall add "db port" "Postgres is on 5433 here, not 5432" +forge catalog # the Start-Here index of everything +``` + +## 5. दूसरा दिन: ledger सीख रहा है + +पहले दिन substrate ने जो कुछ भी सीखा — cortex lessons, remembered facts, verified +code — वह `.forge/ledger/` में claims के रूप में land हुआ। + +```bash +forge ledger stats # what the repo knows, by kind and trust level +forge ledger blame # who minted a claim, every oracle outcome +forge reuse query "" # verified code you already have +``` + + + आगे: किसी टीममेट के ledger को plain git पर, conflict-free, fold करें। + diff --git a/mintlify/hi/installation.mdx b/mintlify/hi/installation.mdx new file mode 100644 index 0000000..11a897c --- /dev/null +++ b/mintlify/hi/installation.mdx @@ -0,0 +1,105 @@ +--- +title: "इंस्टॉलेशन" +description: "एक ही पेड़ पर तीन प्रवेश द्वार: प्लगइन मार्केटप्लेस, npm ग्लोबल, और बिना-रजिस्ट्री github: install — साथ ही कंट्रिब्यूटर symlink सेटअप।" +--- + +Forge एक **एक पेड़, तीन प्रवेश द्वार** डिज़ाइन का पालन करता है: प्लगइन मैनिफ़ेस्ट, +हार्डन्ड इंस्टॉलर, और npm bin सभी उसी `global/` + `source/` पेड़ को संदर्भित करते हैं। +वह चैनल चुनें जो आपके टूल पर सूट करे। + +## एक चैनल चुनें + + + + Claude Code और Codex के लिए। गार्ड्स स्वतः वायर हो जाते हैं; मर्ज करने के लिए कुछ नहीं। + + + किसी भी टूल के लिए। सार्वजनिक npm रजिस्ट्री से `forge` CLI। + + + कोई रजिस्ट्री ज़रूरी नहीं — सीधे रेपो से इंस्टॉल करें। + + + क्लोन करें + `npm link`, या symlink सेटअप के लिए `bash install.sh`। + + + +## आवश्यकताएँ + +- **Node.js >= 20** +- **शून्य रनटाइम निर्भरताएँ** — सब कुछ Node बिल्ट-इन है। वैकल्पिक स्तर + (`FORGE_EMBED` एम्बेडिंग्स, `uicheck visual` के लिए Playwright) ऑप्ट-इन हैं और + कोई आवश्यक निर्भरता नहीं जोड़ते। + +## प्लगइन मार्केटप्लेस + +Claude Code और Codex के लिए अनुशंसित पथ जिसे न किसी टोकन की ज़रूरत है, न क्लोन की: + +```bash +/plugin marketplace add CodeWithJuber/forgekit +/plugin install forgekit +``` + +प्लगइन गार्ड्स को `${CLAUDE_PROJECT_DIR}` के माध्यम से वायर करता है ताकि प्री-एक्शन गेट +और कंप्लीशन गेट परिवेश में चलें। + +## npm ग्लोबल + +किसी भी टूल के लिए, सार्वजनिक npm से: + +```bash +npm install -g @codewithjuber/forgekit +forge doctor # everything green? +``` + +## बिना-रजिस्ट्री github: install + +```bash +npm install -g github:CodeWithJuber/forgekit +``` + +## कंट्रिब्यूटर / लोकल dev + + + +```bash npm link +git clone https://github.com/CodeWithJuber/forgekit.git +cd forgekit +npm link +``` + +```bash install.sh (symlink setup) +git clone https://github.com/CodeWithJuber/forgekit.git +cd forgekit +bash install.sh +``` + + + +इंस्टॉलर हार्डन्ड है: idempotent, symlink-आधारित, बैकअप के साथ, और कोई `curl | sh` नहीं। + +## सत्यापित करें + +आपने जो भी चैनल इस्तेमाल किया हो, इंस्टॉल की पुष्टि करें: + +```bash +forge doctor # tools, guards, MCP auth, config drift, update status +``` + + + `forge doctor` git चेकआउट्स के लिए एक ग़ैर-परेशान करने वाली "commits behind upstream" + सूचना भी दिखाता है। इसे शांत करने के लिए `FORGE_NO_UPDATE_CHECK=1` सेट करें। + हर पथ fail-open है — ऑफ़लाइन या detached HEAD "unknown" रिपोर्ट करता है, कभी error नहीं। + + +## Forge को अद्यतन रखना + +```bash +forge update --check # report whether a newer version is available +forge update # apply the update (git checkout or npm/copy install) +forge update --to # pin or downgrade to a specific version +``` + + + `forge init` चलाने और अपना पहला सब्सट्रेट चेक करने के लिए क्विकस्टार्ट पर जाएँ। + diff --git a/mintlify/hi/introduction.mdx b/mintlify/hi/introduction.mdx new file mode 100644 index 0000000..c27ec31 --- /dev/null +++ b/mintlify/hi/introduction.mdx @@ -0,0 +1,137 @@ +--- +title: "परिचय" +description: "Forge वह संज्ञानात्मक सब्सट्रेट है जो हर स्टेटलेस मॉडल में गायब है — मेमोरी, दूरदर्शिता और गार्डरेल्स — जो हर AI कोडिंग एजेंट को नेटिव कॉन्फ़िग के रूप में मिलता है।" +--- + +**हर AI कोडिंग एजेंट के लिए एक ही मस्तिष्क।** एक बड़ा भाषा मॉडल स्टेटलेस होता है: एक +कॉन्टेक्स्ट विंडो, जो हर कॉल पर मिटा दी जाती है। उसके पास आपकी टीम ने जो सीखा उसकी +कोई मेमोरी नहीं है, किसी एडिट से क्या टूटेगा इसका कोई पूर्वाभास नहीं है, और कोई +प्रवर्तित गार्डरेल्स नहीं हैं। Forge (`@codewithjuber/forgekit`) वही **संज्ञानात्मक +सब्सट्रेट** है — वह परत जो मॉडल द्वारा कोड एडिट करने से _पहले_ चलती है, और साक्ष्य-संदर्भित, +कंटेंट-एड्रेस्ड मेमोरी (जिसे हम "प्रूफ-कैरीइंग मेमोरी" कहते हैं), ह्यूरिस्टिक प्रभाव-पूर्वाभास, +और प्रवर्तित गार्डरेल्स प्रदान करती है — और एक **क्रॉस-टूल कॉन्फ़िग कंपाइलर** जो +उस मस्तिष्क को एक ही बार में हर टूल में नेटिव कॉन्फ़िग के रूप में पहुँचाता है। Claude Code +सबसे गहराई से परखा गया इंटीग्रेशन है; बाकी टूल्स को नेटिव कॉन्फ़िग और MCP टूल्स +मिलते हैं जिनका वास्तविक अभ्यास कम है। + + + + प्रूफ-कैरीइंग मेमोरी जो सत्रों और टीम-साथियों के बीच बनी रहती है। हर सबक, + तथ्य, और सत्यापित पुनरुपयोग एक ऐसा दावा है जो अपना साक्ष्य स्वयं वहन करता है। + + + किसी एडिट की ब्लास्ट रेडियस — कोड ग्राफ़ से पढ़ी गई उन फ़ाइलों का समूह जिन पर + प्रभाव पड़ने की भविष्यवाणी है, उन युग्मित फ़ाइलों सहित जिनका नाम आपने नहीं लिया। + + + डिटरमिनिस्टिक हुक उन नियमों को लागू करते हैं जिन्हें मॉडल कभी नहीं तोड़ सकता। + वे एक कॉन्टेक्स्ट कॉम्पैक्शन को उस तरह पार कर जाते हैं जैसे किसी कॉन्फ़िग फ़ाइल + का गद्य नहीं कर पाता। + + + +## समस्या + +एक बड़ा भाषा मॉडल स्टेटलेस है — एक कॉन्टेक्स्ट विंडो, हर कॉल पर मिटा दी जाती है। + +- उसके पास आपकी टीम ने जो पहले ही सीखा उसकी **कोई मेमोरी नहीं** है। +- उसके पास किसी एडिट से क्या टूटेगा इसका **कोई पूर्वाभास नहीं** है। +- उसके पास **कोई प्रवर्तित गार्डरेल्स नहीं** हैं — गद्य नियम कॉम्पैक्शन के बाद भुला दिए जाते हैं। + +और हर टूल अपनी ही कॉन्फ़िग फ़ाइल चाहता है (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules`, +`GEMINI.md`, MCP…)। Forge वह संज्ञानात्मक सब्सट्रेट है जो तीन गायब चीज़ें उपलब्ध कराता है, +और वह कंपाइलर है जो उसे एक स्रोत से हर टूल तक पहुँचाता है। + +## थीसिस + +एक मॉडल कॉल्स के बीच आपके कोडबेस से नहीं सीख सकता: उसके वेट फ्रोज़ेन हैं और उसकी +वर्किंग मेमोरी हर प्रतिक्रिया के बाद मिट जाती है। मेमोरी, दूरदर्शिता और आत्म-जाँच +उसमें प्रॉम्प्ट नहीं की जा सकतीं — उन्हें _बाहर_ से देना पड़ता है। वही बाहरी परत +संज्ञानात्मक सब्सट्रेट है। औपचारिक रूप से, इनफ़रेंस एक स्थिर फ़ंक्शन `y = f(x)` है जिसमें +कॉल्स के बीच कोई स्टेट नहीं है; Forge वही स्टेट है। + + + + अपने नियम और सब्सट्रेट डिफ़ॉल्ट्स एक कैननिकल स्रोत में लिखें + (`source/rules.json`, `source/substrate.json`, `source/mcp.json`)। + + + `forge sync` उस स्रोत को हर टूल की नेटिव कॉन्फ़िग में कंपाइल करता है — नौ AI + कोडिंग टूल्स और MCP — कंटेंट-हैश हेडर के साथ, ताकि ड्रिफ्ट पहचानी जा सके और + पुनः चलाना नो-ऑप हो। + + + `forge substrate ""` एक डिटरमिनिस्टिक प्री-एक्शन पास चलाता है: अनुमान, + रूटिंग, पुनरुपयोग, कॉन्टेक्स्ट, ब्लास्ट रेडियस, स्कोप, और गोल एंकर। + + + केवल स्वतंत्र ओरैकल्स — टेस्ट्स, CI, कोई मानव स्वीकृति/रिवर्ट — किसी मेमोरी के + कॉन्फ़िडेंस को हिला सकते हैं, इसलिए ग़लत सबक जड़ हो जाने के बजाय क्षय होकर मिट जाता है। + + + +## आपको क्या मिलता है + +- **सत्रों और टीम-साथियों के बीच बनी रहने वाली मेमोरी।** हर सबक, तथ्य, और सत्यापित + पुनरुपयोग _प्रूफ-कैरीइंग मेमोरी (PCM)_ है — साक्ष्य-संदर्भित, कंटेंट-एड्रेस्ड + मेमोरी के लिए हमारा नाम: एक दावा जो अपने साक्ष्य के संदर्भ वहन करता है और तब तक + विश्वसनीय नहीं माना जाता जब तक कि स्वतंत्र ओरैकल्स उसके कॉन्फ़िडेंस को न्यूनतम सीमा से + ऊपर न उठा दें। "प्रूफ" वही साक्ष्य-मार्ग है, न कि कोई औपचारिक प्रमाण। +- **चीज़ें तोड़ने से पहले दूरदर्शिता।** पूछें "`verifyToken` बदलने से क्या टूटता है?" + और कोड ग्राफ़ से ब्लास्ट रेडियस पाएँ, जिसमें वे युग्मित फ़ाइलें भी शामिल हैं जिनका + नाम आपने कभी नहीं लिया। +- **ऐसे गार्डरेल्स जिन्हें भुलाया नहीं जा सकता।** डिटरमिनिस्टिक हुक संरक्षित पथ, + लागत बजट, और डूम-लूप डिटेक्शन लागू करते हैं — वे कॉन्टेक्स्ट कॉम्पैक्शन को पार कर जाते हैं। +- **ऐसा काम जो अंत तक पूरा हो।** एक कंप्लीशन गेट प्रति सत्र एक बार "done" रोकता है + जब कोड में परिवर्तन हुआ पर कोई डॉक या स्टेट आर्टिफ़ैक्ट साथ नहीं आया, और मरम्मत + चेकलिस्ट को उत्तर के रूप में देता है। +- **9 टूल्स के लिए एक कॉन्फ़िग।** अपने नियम एक बार लिखें; Forge हर टूल की नेटिव + कॉन्फ़िग निकालता है, साथ ही Roo और VS Code के लिए MCP। शून्य रनटाइम निर्भरताएँ — + एक Node CLI, git में सादी फ़ाइलें, कोई सर्वर नहीं। + +## Forge किन टूल्स को फ़ीड करता है? + +Forge **नौ टूल्स** के लिए कॉन्फ़िग निकालता है, साथ ही Roo Code और VS Code के लिए +एक MCP सर्वर: Claude Code, Codex, Cursor, Gemini, Aider, Copilot, Windsurf/Devin, +Zed, और Continue। हर एक अपनी ही नेटिव फ़ाइल से वही नियम पढ़ता है। + +## ईमानदार सीमाएँ + +Forge हर जगह अपनी सीमा स्वयं बताता है। + + + Forge नियम-ड्रिफ्ट को **कम करता है, समाप्त नहीं करता।** यह एक पारदर्शिता और + विश्वसनीयता परत है, टेस्ट्स, समीक्षा, या निर्णय का विकल्प नहीं। + + +- **गार्ड्स केवल वही लागू करते हैं जो हुक के रूप में व्यक्त किया जा सके** (पथ, फ़ॉर्मैट, + डिफ़-साइज़, बजट)। अर्थपूर्ण नियम ("फ़ंक्शनल पसंद करें") गद्य रहते हैं और कभी-कभी + अनदेखे रह जाएँगे। +- **सत्यापन कम करता है, प्रमाणित नहीं करता।** क्रू वेरिफ़ायर और हैलुसिनेटेड-सिंबल + फ़्लैग समीक्षा भार कम करते हैं; वे कोड को सही सिद्ध नहीं करते। +- **कोई वेट-स्तरीय अधिगम नहीं।** `recall` / `cortex` केवल फ़ाइल-और-प्रॉम्प्ट मेमोरी है — न + RL, न फ़ाइन-ट्यूनिंग। +- **इम्पैक्ट ग्राफ़ regex-अनुमानित है** — रूढ़िवादी, कोई साउंड कॉल ग्राफ़ नहीं। +- **टेस्ट्स और मानव सुधार हमेशा जीतते हैं।** + + + Forge **बीटा** में है। कोर (`init`, `sync`, `substrate`, `impact`, `ledger`, guards) + परखा हुआ है और दैनिक उपयोग में है; कुछ फ़्लैग `1.0` से पहले बदल सकते हैं। + + +## अगले कदम + + + + इंस्टॉल करें, `forge init` चलाएँ, और अपना पहला कार्य सब्सट्रेट के माध्यम से पास कराएँ। + + + चार-परत कंपाइलर, प्रूफ-कैरीइंग मेमोरी, और प्री-एक्शन गेट। + + + हर कमांड, Core, Memory, Substrate, Quality, और Config के अनुसार समूहित। + + + एक टीम-साथी के लेजर को सादे git के ऊपर, संघर्ष-रहित तरीके से मिलाएँ। + + diff --git a/mintlify/hi/quickstart.mdx b/mintlify/hi/quickstart.mdx new file mode 100644 index 0000000..2900b23 --- /dev/null +++ b/mintlify/hi/quickstart.mdx @@ -0,0 +1,107 @@ +--- +title: "क्विकस्टार्ट" +description: "Forge इंस्टॉल करें, एक स्रोत से हर टूल का कॉन्फ़िग निकालें, और अपना पहला प्री-एक्शन गेट चलाएँ — लगभग 60 सेकंड में।" +--- + +शून्य से लेकर एक कॉन्फ़िगर किए गए रेपो और अपने पहले सब्सट्रेट चेक तक लगभग एक मिनट में पहुँचें। + +## 1. इंस्टॉल करें + + + +```bash Plugin (Claude Code / Codex) +/plugin marketplace add CodeWithJuber/forgekit +/plugin install forgekit +``` + +```bash npm (any tool) +npm install -g @codewithjuber/forgekit +``` + +```bash No registry +npm install -g github:CodeWithJuber/forgekit +``` + + + +प्लगइन पथ Claude Code और Codex के लिए अनुशंसित है — गार्ड्स स्वतः वायर हो जाते हैं +और मर्ज करने के लिए कुछ नहीं है। पूरे मैट्रिक्स के लिए [Installation](/hi/installation) +देखें, जिसमें symlink dev सेटअप भी शामिल है। + +## 2. एक रेपो कॉन्फ़िगर करें + + + + ```bash + cd ~/your-project + forge init + ``` + यह `AGENTS.md`, `CLAUDE.md`, `.gemini/settings.json`, `.aider.conf.yml`, और बाकी + निकालता है — साथ ही वह `.gitattributes` यूनियन-मर्ज नियम जो लेजर के लिए ज़रूरी है। + Claude Code, Codex, Cursor, Gemini, Aider, Copilot, Windsurf, Zed, और Continue + अब **समान** नियम पढ़ते हैं, प्रत्येक अपनी नेटिव फ़ाइल से। + + + ```bash + forge doctor + ``` + इंस्टॉल किए गए टूल्स, गार्ड्स, MCP ऑथ, और कॉन्फ़िग ड्रिफ्ट की पास/फ़ेल जाँच। + + + `source/rules.json` संपादित करें (या एक प्रति-रेपो `.forge/rules.json` रखें), फिर पुनः कंपाइल करें: + ```bash + forge sync + ``` + `sync` idempotent है — यह केवल वही पुनर्लिखित करता है जो बदला है। + + + +## 3. प्री-एक्शन गेट चलाएँ + +सब्सट्रेट वह परत है जो मॉडल द्वारा कोड एडिट करने से _पहले_ चलती है। एक कमांड पूरा +गेट चलाता है: + +```bash +forge substrate "Change verifyToken in src/auth.js to require length > 20; update tests" +# → assumption verdict · cheapest capable model · predicted blast radius +# (including files you didn't name) · scope clusters · verification checklist +``` + + + Claude Code पर सब्सट्रेट **हर प्रॉम्प्ट पर स्वचालित रूप से** एक `UserPromptSubmit` + हुक के माध्यम से चलता है — केवल सलाहकारी, साफ़ कार्यों पर मौन। हर दूसरा टूल एक + नेटिव कॉन्फ़िग नियम पाता है साथ ही 19 MCP टूल्स जिन्हें वह स्वयं कॉल कर सकता है। + + +अगर `forge substrate` `ASK FIRST` कहता है, तो एडिट करने से पहले लौटाए गए प्रश्न पूछें। +किसी भी परिवर्तनकारी बदलाव से पहले पूर्वानुमानित प्रभावित फ़ाइलें — ब्लास्ट रेडियस — पढ़ें। + +```bash +forge substrate "" --json # machine-readable verdict +forge impact # the blast radius on its own +``` + +## 4. अतिरिक्त सुविधाएँ खोजें + +```bash +forge atlas build # index this repo's symbols → .forge/atlas.json +forge atlas query useAuth # where is it defined? (cheaper than grep-and-read) +forge atlas has useAuth # does it exist? "not found" = likely hallucinated +forge recall add "db port" "Postgres is on 5433 here, not 5432" +forge catalog # the Start-Here index of everything +``` + +## 5. दूसरा दिन: लेजर सीख रहा है + +सब्सट्रेट ने दिन एक में जो कुछ सीखा वह `.forge/ledger/` में दावों के रूप में उतरा। +यह प्रूफ-कैरीइंग मेमोरी है — अब यह लाभ देना शुरू करती है: + +```bash +forge ledger stats # what the repo knows, by kind and trust +forge ledger blame # who minted a claim, every oracle outcome +forge reuse query "" # verified code you already have +``` + + + पढ़ें कि प्री-एक्शन गेट अपने चरणों को एक ही वर्डिक्ट में कैसे संयोजित करता है। + diff --git a/mintlify/zh-CN/cli/config.mdx b/mintlify/zh-CN/cli/config.mdx new file mode 100644 index 0000000..9128661 --- /dev/null +++ b/mintlify/zh-CN/cli/config.mdx @@ -0,0 +1,86 @@ +--- +title: "Config 命令" +description: "提供商、成本、看板、品牌、atlas 和技术栈:config、cost、dash、brand、atlas、stack —— 外加 v0.19+ 的 report 与 tools 命令。" +--- + +Config 组涵盖提供商、可观测性、代码图和技术栈检测。 + +## `forge config` + +提供商设置 —— 显示 / 切换 / 添加提供商,设置默认模型。 + +```bash +forge config # show current config +forge config switch +forge config add +``` + +## `forge cost` + +通过实测的阶段因子给出真实的每日花费。 + +```bash +forge cost # real per-day spend +forge cost --stages # measured per-stage cost factors +``` + + + **只报告实测过的阶段** —— 没有事件的阶段会显示"no data",而不是给出默认值。 + + +## `forge dash` + +基于账本、指标和爆炸半径的本地看板。 + +```bash +forge dash # localhost-only, read-only (default port 4242) +``` + +## `forge brand` + +打印当前生效的品牌 token 映射。 + +```bash +forge brand +``` + +品牌以单一 token(`brand.json`)存储;换品牌只需一次编辑。 + +## `forge atlas` + +构建 / 查询代码图。 + +```bash +forge atlas build [path] # walk the tree → .forge/atlas.json +forge atlas query "what calls Z" +forge atlas has # hallucinated-symbol check +``` + +atlas 是纯 JSON —— 任何工具都能读,不需要 MCP。 + +## `forge stack` + +从仓库的清单文件中检测其真实技术栈。 + +```bash +forge stack +``` + +读取 `package.json`、`pyproject.toml`、`go.mod`、`Cargo.toml`、`Gemfile`、 +`composer.json`、`pom.xml` / `build.gradle` 以及 `*.csproj`,报告语言、框架、包管理器,以及仓库**真正的**测试命令 —— 这些会喂给基座的验证清单。 + +## `forge report` v0.19+ + +生成仓库 Forge 状态的静态 HTML 报告 —— 把账本、指标和爆炸半径渲染到一个自包含的文件里,可以分享或存档。 + +```bash +forge report +``` + +## `forge tools` v0.19+ + +选择该仓库的主要 AI 编码工具,并接入匹配的 `.gitignore` 条目,让生成的配置和 `.forge/` 产物在你的环境下被正确忽略。 + +```bash +forge tools +``` diff --git a/mintlify/zh-CN/cli/core.mdx b/mintlify/zh-CN/cli/core.mdx new file mode 100644 index 0000000..712d61e --- /dev/null +++ b/mintlify/zh-CN/cli/core.mdx @@ -0,0 +1,69 @@ +--- +title: "Core 命令" +description: "引导并维护一个仓库:init、sync、doctor、catalog、docs 和 update。" +--- + +Core 组用于引导一个仓库并保持其健康。 + +## `forge init` + +搭建该仓库的配置 —— 从一个共享源为每个工具生成配置。 + +```bash +forge init +``` + +生成 `AGENTS.md`、`CLAUDE.md`、`.gemini/settings.json`、`.aider.conf.yml` 以及其他文件(加上给 Roo Code 与 VS Code 的 MCP 服务器配置),以及账本需要的 `.gitattributes` union-merge 规则。 + +## `forge sync` + +把规范源重新编译为每个工具的原生配置文件。 + +```bash +forge sync +``` + +幂等 —— 只重写发生了变化的内容。修改 `source/rules.json` 或仓库级 `.forge/rules.json` 之后运行它。 + +## `forge doctor` + +对已安装工具、护栏、MCP 认证和配置漂移做健康检查。 + +```bash +forge doctor +``` + +跨工具、护栏、MCP 接线、配置漂移和更新状态给出通过/失败结果。每条路径都失败开放。当配置了自定义网关时,**gateway models** 一行会打印解析后的 `tier → model` 映射。 + +## `forge catalog` + +Start Here —— 列出每个工具、crew 和护栏,并附一行原因说明。 + +```bash +forge catalog +``` + +## `forge docs` + +文档 ↔ 代码 漂移。 + +```bash +forge docs check # registry reconcile — commands, env vars, MCP tools, CHANGELOG +forge docs sync # diff-driven stale-docs sweep +``` + + + 当命令、环境变量、MCP 工具或 CHANGELOG 与代码不一致时,`docs check` 会让 CI 失败。`docs sync` 扫描 diff 并报告 UPDATED / STALE / VERIFIED-UNAFFECTED。 + + +## `forge update` + +跨三种安装模式的自更新。 + +```bash +forge update # apply the update (git checkout or npm/copy install) +forge update --check # report whether a newer version is available +forge update --to # pin or downgrade to a specific version (v0.19+) +``` + +每条路径都失败开放 —— 离线、没有上游或 detached HEAD 会返回"unknown",从不作为错误。`FORGE_NO_UPDATE_CHECK=1` 可静默 doctor 的提示。 diff --git a/mintlify/zh-CN/cli/memory.mdx b/mintlify/zh-CN/cli/memory.mdx new file mode 100644 index 0000000..8c04c96 --- /dev/null +++ b/mintlify/zh-CN/cli/memory.mdx @@ -0,0 +1,103 @@ +--- +title: "Memory 命令" +description: "跨会话与团队记忆:cortex、recall、remember、brain、ledger、reuse、handoff 和 decide —— 全部汇聚到携证账本。" +--- + +Memory 组管理跨会话与团队记忆。所有内容都汇聚到 `.forge/ledger/` 下的携证账本。模型说明见 [携证记忆](/zh-CN/concepts/proof-carrying-memory)。 + +## `forge cortex` + +自我纠正的项目记忆 —— 从纠错中挖掘出来的经验。 + +```bash +forge cortex status # what's been learned +forge cortex why # why a lesson applies here +``` + +## `forge recall` + +管理跨会话的个人记忆。 + +```bash +forge recall list # facts the recall-load guard injects next session +forge recall add "db port" "Postgres is on 5433 here, not 5432" +forge recall consolidate # summarize (advisory, human-reviewable) +``` + +## `forge remember` + +给该仓库的可移植记忆添加一条可提交到仓库的持久事实。 + +```bash +forge remember "" +``` + +## `forge brain` + +显示或重建可移植的项目记忆索引。 + +```bash +forge brain # show the index +forge brain --rebuild # rebuild it +``` + +## `forge ledger` + +携证记忆 —— 以内容寻址的声明存储。 + +```bash +forge ledger stats # what the repo knows, by kind and trust level +forge ledger verify # re-check claims are in normal form +forge ledger show # a claim and its evidence +forge ledger blame # who minted it, every oracle outcome, per-author trust +forge ledger query "" # retrieve by relevance +forge ledger ratify # human accept +forge ledger retract # tombstone a claim +forge ledger merge # fold a teammate's ledger in, conflict-free +forge ledger import # bridge legacy stores into the ledger +``` + +加 `--personal` 使用每用户级别的账本。 + +## `forge reuse` + +携证代码缓存 —— 只有当证据仍然成立时才服务。 + +```bash +forge reuse query "" # verified code you already have +forge reuse mint "" --file # add an artifact to the cache +forge reuse stats # cache stats +``` + +## `forge handoff` + +有界的会话快照 —— 重写 `.forge/state.md`,每次会话开始时重新注入。 + +```bash +forge handoff "" --next "" +``` + +## `forge decide` + +只追加的决策日志 —— 在 `.forge/decisions.md` 中的 `D-####` 精简版 ADR 条目。 + +```bash +forge decide " — " +forge decide # read the log before re-deciding +``` + +## `forge know` v0.19+ + +把一条事实路由到它正确的存储归宿 —— 决定一段知识属于 `recall`、`remember`/`brain`、一个决策还是一条 cortex 经验,并把它落在那里。 + +```bash +forge know "" +``` + +## `forge deja` v0.19+ + +类似过往工作查找 —— 从账本中找出与你即将做的事类似的既有工作,让你复用证据而不是重新生成。 + +```bash +forge deja "" +``` diff --git a/mintlify/zh-CN/cli/overview.mdx b/mintlify/zh-CN/cli/overview.mdx new file mode 100644 index 0000000..ff17b31 --- /dev/null +++ b/mintlify/zh-CN/cli/overview.mdx @@ -0,0 +1,50 @@ +--- +title: "CLI 概览" +description: "每一个 forge 命令,按 Core、Memory、Substrate、Quality 和 Config 分组 —— 命令面被视为数据,并由严格的漂移检查与文档对账。" +--- + +`forge` 命令面以数据形式定义 (`src/commands.js`),并通过 `forge docs check` 与文档对账,因此任何命令的加入或消失都逃不过文档的注意。命令被组织成五个组。 + + + + 引导与维护:`init`、`sync`、`doctor`、`catalog`、`docs`、`update`。 + + + 跨会话与团队记忆:`cortex`、`recall`、`remember`、`brain`、`ledger`、`reuse`、`handoff`、`decide`。 + + + 预动作门及其各阶段:`substrate`、`preflight`、`route`、`impact`、`scope`、`context`、`anchor`、`diagnose`、`imagine`、`lean`。 + + + 验证与安全:`verify`、`scan`、`spec`、`taste`、`uicheck`、`harden`。 + + + 提供商、成本、看板、品牌、atlas、技术栈:`config`、`cost`、`dash`、`brand`、`atlas`、`stack`。 + + + +## 约定 + +- **默认建议模式。** 设置 `FORGE_ENFORCE=1` 可让基座把最强的信号(空洞的 prompt、无法组装的必需上下文、爆炸半径超过默认的 25 文件阈值)变为硬阻断。 +- **默认安静。** 每个命令的 `Forge — …` 标题只是品牌装饰,藏在 `--verbose` / `FORGE_VERBOSE` 后面;命令会先输出结果。 +- **管道友好输出。** 管道下是纯文本;TTY 下加上品牌调色板颜色和置信度进度条。`NO_COLOR` 关闭颜色,`FORCE_COLOR=1` 强开。 +- **`--json`** 在基座和大多数分析命令上可用,便于脚本化。 + + + 运行 `forge --help` 获取始终最新的列表,或运行 `forge catalog` 查看每个工具、crew 和护栏并附一行原因说明的 Start-Here 索引。 + + +## v0.19+ 新增 + +一批命令与参数正在 v0.19 系列陆续落地。它们记录在各自的组页面并在文中标注: + +| 命令 / 参数 | 组 | 作用 | +| ---------------------- | -------- | ----------------------------------------------- | +| `forge know` | Memory | 把一条事实路由到它正确的存储归宿。 | +| `forge deja` | Memory | 类似过往工作查找。 | +| `forge precommit` | Quality | 提交级验证门。 | +| `forge radar` | Quality | 依赖时效性同心圆。 | +| `forge report` | Config | 仓库 Forge 状态的静态 HTML 报告。 | +| `forge tools` | Config | 主工具选择 + gitignore 接线。 | +| `forge verify --deep` | Quality | 多镜头共识验证。 | +| `forge update --to` | Core | 锁定或回退到指定版本。 | diff --git a/mintlify/zh-CN/cli/quality.mdx b/mintlify/zh-CN/cli/quality.mdx new file mode 100644 index 0000000..c7c6277 --- /dev/null +++ b/mintlify/zh-CN/cli/quality.mdx @@ -0,0 +1,81 @@ +--- +title: "Quality 命令" +description: "验证与安全:verify、scan、spec、taste、uicheck 和 harden —— 外加 v0.19+ 的 precommit 与 radar 门。" +--- + +Quality 组是验证与安全的入口。这些如何组合,详见 [验证门](/zh-CN/concepts/verification-gates)。 + +## `forge verify` + +独立验证门 —— 测试 + 幻觉符号 + 溯源。 + +```bash +forge verify +forge verify --deep # multi-lens consensus (v0.19+) +``` + +## `forge scan` + +skill 门 —— 在安装前审查某个 skill 或 MCP 服务器是否存在注入 / RCE / 泄露风险。 + +```bash +forge scan +``` + +## `forge spec` + +规约即契约 —— init (OpenSpec)、锁定、并检查漂移。 + +```bash +forge spec init +forge spec lock +forge spec check +``` + +## `forge taste` + +为该仓库启用一个 UI 品味工具(不带参数会列出选项)。 + +```bash +forge taste # list the profiles +forge taste # brutalist · corporate · editorial · minimalist · playful +``` + +写入 `DESIGN.md` 并参数化 `uicheck design` 门的阈值。 + +## `forge uicheck` + +确定性 UI 检查。 + +```bash +forge uicheck contrast # WCAG contrast ratio +forge uicheck fingerprint # deterministic design fingerprint +forge uicheck design # slop-distance + conformance gate +forge uicheck visual # Playwright-rendered check (opt-in tier) +``` + +## `forge harden` + +接入安全控制 —— gitleaks pre-commit + 沙箱设置。 + +```bash +forge harden +``` + +## `forge precommit` v0.19+ + +提交级门 —— 在 commit 时运行验证底线,以便在部分或未验证的工作落库之前捕获它们。 + +```bash +forge precommit +``` + +## `forge radar` v0.19+ + +依赖时效性同心圆 —— 按当前程度把项目的依赖分组,让陈旧或漂移的依赖在咬人之前浮现。 + +```bash +forge radar +``` + +如何阅读这些环,见 [保持依赖时效](/zh-CN/guides/radar-deps) 指南。 diff --git a/mintlify/zh-CN/cli/substrate.mdx b/mintlify/zh-CN/cli/substrate.mdx new file mode 100644 index 0000000..14b06bc --- /dev/null +++ b/mintlify/zh-CN/cli/substrate.mdx @@ -0,0 +1,99 @@ +--- +title: "Substrate 命令" +description: "预动作门及其可单独调用的各阶段:substrate、preflight、route、impact、scope、context、anchor、diagnose、imagine 和 lean。" +--- + +Substrate 组即预动作门。`forge substrate` 把其余命令合成为单一裁决;每个阶段也可以单独调用。流水线详情见 [预动作门](/zh-CN/concepts/pre-action-gate)。 + +## `forge substrate` + +一个预动作门:假设、路由、影响、范围、记忆、验证。 + +```bash +forge substrate "" +forge substrate "" --json +``` + +如果返回 `okToProceed:false`,在编辑前先提出返回的 `assumption.questions`。 + +## `forge preflight` + +假设检查 —— 任务提到的、仓库中没有定义的东西。 + +```bash +forge preflight "" +``` + +## `forge route` + +为一个任务推荐性价比最高、能胜任的模型。 + +```bash +forge route "" +forge route gateway # emit LiteLLM gateway config +``` + +## `forge impact` + +从 atlas 图中预测某个符号或文件的爆炸半径。 + +```bash +forge impact +``` + +## `forge scope` + +把文件分解成独立的簇 —— 外加你没点名的耦合文件。 + +```bash +forge scope +``` + +## `forge context` + +有预算的上下文组装 + 完整性门 —— 一次编辑**需要**知道的东西。 + +```bash +forge context "" +``` + +对预测的编辑集合使用集合覆盖来组装一个有预算的上下文,套用一层压缩阶梯,并报告计算出的缺失集合。 + +## `forge anchor` + +目标漂移检查 —— 你实际(git)变更是否仍然对准既定目标? + +```bash +forge anchor set "" # persist the goal across sessions +forge anchor show +forge anchor clear +``` + +## `forge diagnose` + +死循环检查 —— 记录一次失败;相同签名出现 3 次会生成一份诊断 + 升级。 + +```bash +forge diagnose "" +``` + +## `forge imagine` + +后果模拟 —— 为某个任务预测的破坏点 + 最小空跑测试集。 + +```bash +forge imagine "" +forge imagine "" --run # execute the minimal suite sandboxed +``` + +## `forge lean` + +范围最小性 (M5) —— 衡量 diff 的足迹与任务要求之间的差距。 + +```bash +forge lean +``` + + + `route`、`impact`、`scope`、`context`、`anchor` 和 `lean` 都会在 `forge substrate` 里运行。当你只需要单一信号时才单独调用它们。 + diff --git a/mintlify/zh-CN/concepts/config-compiler.mdx b/mintlify/zh-CN/concepts/config-compiler.mdx new file mode 100644 index 0000000..e312ec0 --- /dev/null +++ b/mintlify/zh-CN/concepts/config-compiler.mdx @@ -0,0 +1,80 @@ +--- +title: "四层配置编译器" +description: "一次编写基座;forge sync 把它编译到每个工具的原生配置中。四层是大脑的表达方式;编译器是它的交付方式。" +--- + +你一次编写基座。`forge sync` 把这个源编译到每个工具的原生配置中。四层是_大脑的表达方式_;编译器是_大脑的交付方式_。 + +```mermaid +flowchart TD + S["source/ · rules.json · substrate.json · mcp.json"] -->|"forge sync — content-hash + DO-NOT-EDIT headers"| N["native configs · CLAUDE.md · AGENTS.md · .cursor · .gemini · .aider"] + S -. configures .-> L + subgraph L["the four layers"] + direction LR + T["tools · model-invoked skills"] + C["crew · isolated sub-agents"] + G["guards · deterministic hooks"] + M["mcp · atlas + substrate server"] + end +``` + +## 一个源,多个发射器 + +规则**只写一次**(`source/rules.json`);一个确定性编译器 (`forge sync`) 以每个工具的原生格式发射,附带内容哈希头,因此漂移可检测,重复运行是无操作的。没有任何规则被写两次。规范源由三个文件组成: + +| 源文件 | 存放什么 | +| ----------------------- | -------------------------------------------------------------------- | +| `source/rules.json` | 规范的工程规则(git、测试、安全、风格)。 | +| `source/substrate.json` | 认知基座默认值 —— 阈值、路由、LLM 旋钮。 | +| `source/mcp.json` | 发射到每个工具的 MCP 服务器定义。 | + +## 四层 + +每一层都有品牌名,并且跨工具发射。 + + + + `~/.forge/tools/` → `~/.claude/skills/`。模型可调用的 skill,遵循 `SKILL.md` 标准(`name` + `description` 前置元数据)。 + + + `~/.forge/crew/` → `~/.claude/agents/`。上下文隔离的子代理,例如 scout、verifier 和 frontend-verifier。 + + + `~/.forge/guards/` → `settings.json` 钩子。**唯一_强制_而非建议的层。** 一个 guard 是模型无法漂移的确定性钩子。`CLAUDE.md` 中的散文规则被承认后会在压缩之后被遗忘;guard 不会。任何可强制的不变量都属于这里。 + + + Forge 提供一个 stdio 服务器 (`src/cortex_mcp.js`),暴露 19 个 MCP 工具:基座检查 (`substrate_check` / `predict_impact` / `assumption_gate` / …)、记忆的读_与_写 (`forge_remember`、ledger ratify/retract),以及运维/健康。 + + + +跨越四层的关注点:**atlas**(代码图)、**lean**(极简性 —— 既作为一个工具,也作为一个 Stop 阶段的 guard 出货,所以不管模型是否调用它都会生效)、**recall**(记忆)。 + +## 用 guard 代替散文 + +模型可以漂移的规则活在散文里;它**绝对不能**违反的规则活在 guard(确定性 shell 钩子)里。guard 不会在上下文压缩后被遗忘。 + + + 把每一条可强制的不变量从 `CLAUDE.md` 中挪到 guard 里,让散文保持精简。这是 Forge 设计中最重要的一条纪律。 + + +## 经过验证的跨工具发射矩阵 + +Forge 为**九个工具**发射配置,加上给 Roo Code 与 VS Code 的 MCP 服务器。每一行都对照过厂商文档。 + +| 工具 | 原生目标 | Forge 如何发射 | +| ------------------ | ---------------------------------------------------------------- | --------------------------------------------------------------------- | +| **Claude Code** | `CLAUDE.md`(+ `.claude/rules/*.md`、`settings.json`) | 首行是 `@AGENTS.md` 的精简 `CLAUDE.md`;guards → settings | +| **Codex** | 原生 `AGENTS.md`(32 KiB 上限) | 根目录规范 `AGENTS.md` **就是**源 | +| **Cursor** | `AGENTS.md` + `.cursor/rules/*.mdc` | 扁平规则用 `AGENTS.md`;需要作用域时用 `.mdc` | +| **Gemini** | `GEMINI.md`,或通过 `context.fileName` 选用 `AGENTS.md` | 写 `.gemini/settings.json` 以避免第二份副本 | +| **Aider** | 通过 `.aider.conf.yml` 的 `read:` 指向的 `CONVENTIONS.md` | 生成含 `read: AGENTS.md` 的 `.aider.conf.yml` | +| **Copilot** | 根 `AGENTS.md` + `.github/copilot-instructions.md` | 依赖根 `AGENTS.md`;可选 `.github` 指针 | +| **Windsurf/Devin** | `AGENTS.md` 自动发现(上限 6k/12k 字符) | 根 `AGENTS.md` 在上限之内;区分 `.windsurf` 与 `.devin` | +| **Zed** | 含 `AGENTS.md` 的优先级列表首匹配 | 发射 `AGENTS.md`;doctor 标注任何被遮蔽的遗留文件 | +| **Continue** | `.continue/rules/*.md` + `.continue/mcpServers/*.yaml` | 发射规则文件加上 Forge MCP 服务器配置 | + +Roo Code 和 VS Code 通过 `forge init` 拿到 Forge MCP 服务器(`.roo/mcp.json`、`.vscode/mcp.json`),而非规则文件。 + + + **字符上限是真的。** Codex 在 32 KiB 处截断,Windsurf 在 6k/12k 处截断。`forge sync` 会强制一个源大小预算,以防配置被悄悄截断。 + diff --git a/mintlify/zh-CN/concepts/cross-session-memory.mdx b/mintlify/zh-CN/concepts/cross-session-memory.mdx new file mode 100644 index 0000000..3e89795 --- /dev/null +++ b/mintlify/zh-CN/concepts/cross-session-memory.mdx @@ -0,0 +1,70 @@ +--- +title: "跨会话记忆" +description: "会话锚定、完成门、handoff 快照和决策日志 —— 消灭会话失忆和半途而废的那一层。" +--- + +这一层要消灭两种失败模式:**半途而废的工作**(代码变了,但依赖它的产物没跟上)和**会话失忆**(下一场会话重新假设这场会话已知的东西)。指令提升正确行为的_概率_;确定性钩子保证一个_底线_。 + +## 会话锚定 + +在 `SessionStart` 时 (`src/session.js`),Forge 每次会话记录一次 `HEAD`,清理一周前的会话产物,并注入一份新鲜的定位: + + + + 从过往纠错中挖出的 cortex 经验。 + + + 既定目标,用来衡量漂移。 + + + 上一场会话写下的有界 `.forge/state.md`。 + + + 近期提交和未提交变更 —— 是证据,不是先验。 + + + +新会话依据证据而非先验来定位。 + +## 完成门 + +Stop 路径上唯一被允许回答的 guard 是 `completion-gate.sh` (`src/gate.js`)。它同步运行;负责挖掘经验的 `cortex.sh stop` 始终在分离进程中,永远不会阻塞。 + +变更集是**会话范围**的:committer time 大于等于会话开始时间的提交涉及到的文件,加上工作树变更减去 `SessionStart` 时快照的脏文件 —— 因此已存在的编辑、分支切换和 `git pull` 永远不会被算到代理头上。 + + + 如果代码动了但没有对应的文档或状态产物跟进,该门会**阻断一次**,阻断原因就是修复清单。其他情况一律放行,内部错误也一律放行(失败开放)。`FORGE_STOPGATE=0` 可禁用它。 + + +修复清单指向能收尾这项工作的工具: + +```bash +forge docs sync # sweep the diff for stale doc mentions +forge handoff "" --next "" # write the bounded session snapshot +forge decide " — " # record a choice so no session re-decides it +``` + +## Handoff 与决策 + +两个存储让知识跨越会话: + +| 存储 | 语义 | +| ---------------------- | ------------------------------------------------------------------------------------ | +| `.forge/state.md` | 一份有界的**重写**(快照)—— loader 成本永远保持 `O(bound)`。 | +| `.forge/decisions.md` | 只追加的**精简版 ADR**(`D-####`),并带一份机器可读的决策账本副本。 | + +两者在写入时都会拒绝密钥。`state.md` 在每次会话开始时被重新注入;`decisions.md` 在重新决定过往会话已经定下的事项之前会被读一遍。 + +```bash +forge handoff "" --next "" +forge decide " — " +forge decide # read the log before re-deciding +``` + +## 由 diff 驱动的文档扫描 + +`forge docs sync` 回答 diff 形式的问题:变化过的标识符(路径、定义、被调用的符号,来自新增_与_删除两侧的行)对每一份文档产物做扫描 → UPDATED / STALE(带 file:line 命中)/ VERIFIED-UNAFFECTED,并记录原因。它是纯粹的报告工具;完成门提供牙齿。 + + + `recall` 和 `cortex` 只是文件和提示词记忆 —— **不是**权重级学习。合并是一个可能出现幻觉的摘要,所以它一直是建议性的、可人工审阅的、且不含密钥。 + diff --git a/mintlify/zh-CN/concepts/model-routing.mdx b/mintlify/zh-CN/concepts/model-routing.mdx new file mode 100644 index 0000000..9658c88 --- /dev/null +++ b/mintlify/zh-CN/concepts/model-routing.mdx @@ -0,0 +1,61 @@ +--- +title: "模型路由" +description: "一份确定性、可 diff 的评分表在分发前挑出性价比最高、能胜任的模型层级 —— 并为自托管网关提供一个保底重映射。" +--- + +Forge 在分发**之前**推荐性价比最高、能胜任任务的模型,依据是一份你可以在仓库中阅读的确定性评分表 (`src/model_tiers.json`)。与在代理内部于请求时决策的网关不同,路由决策在 git 中是可见且可 diff 的。 + +## 推荐一个层级 —— `forge route` + +```bash +forge route "" # cheapest capable model tier for the task +forge route gateway # emit LiteLLM gateway config +``` + +推荐使用的是在标注样本库(英文 + Hinglish 行)上的示例 k-NN 数学,基于重叠相似度指标并有置信度门 —— 不是关键词查表。 + + + 从推荐的 `route.tier` 开始,只有当外部验证器失败之后再升级,永远不要预防性升级。这样既压得住花费,又不会在任务确实需要能力时封顶。 + + +## 先意图,再层级 + +路由与意图检测 (`src/intent.js`) 共享同一套数学:一段 prompt 通过同一个示例 k-NN 估计器映射到意图。注意两者使用不同的停用集合 —— route 把泛化动词(`fix` / `add` / `build`)视为复杂度噪声,而这些动词恰好是意图信号。 + +## 层级表 + +层级表 (`src/model_tiers.json`) 按家族(haiku / sonnet / opus / fable)固定了公开的 Anthropic 模型 ID。文档中的价格通过 docs check 与这份文件对账,所以散文和表格无法漂移。 + +## 自托管网关重映射 + +自托管的 LiteLLM 或代理网关会提供自己命名的模型,直接把库存 ID 原样发过去会 404。当配置了非默认的网关 base URL 时,Forge (`src/gateway_model_map.js`) **每个进程仅一次**拉取 `GET /v1/models`,并对每个层级家族对被宣告的每一个 id 打分: + + + + 家族关键词(haiku / sonnet / opus / fable)必须匹配 —— 这是硬门。 + + + 在同一家族内,由层级名字 token 的 `setOverlap` 系数挑出最佳匹配。 + + + 平局时倾向于最接近规范名的 id。 + + + + + 该重映射**只**在解析出的 id 是一个_库存_ ID 时才咨询网关 —— 显式的 `.forge/providers.json` 别名或 `ANTHROPIC_MODEL` 覆盖永远不会被触碰。当没有网关、`/v1/models` 不可达或家族不匹配时,它会保底为库存 ID,因此直连 `api.anthropic.com` 的用户会得到逐字节一致的结果。 + + +`forge doctor` 的 **gateway models** 行会打印解析后的 `tier → model` 映射,便于校验。 + +## 提供商与成本 + +```bash +forge config # show / switch / add providers, set the default model +forge cost # real per-day spend +forge cost --stages # measured per-stage cost factors +``` + + + `forge cost --stages` **只报告实测过的阶段** —— 没有事件的阶段会显示"no data",而不是给出默认值。一个数字在被测量之前只是假设。 + diff --git a/mintlify/zh-CN/concepts/pre-action-gate.mdx b/mintlify/zh-CN/concepts/pre-action-gate.mdx new file mode 100644 index 0000000..894719b --- /dev/null +++ b/mintlify/zh-CN/concepts/pre-action-gate.mdx @@ -0,0 +1,84 @@ +--- +title: "预动作门" +description: "forge substrate 在模型编辑代码之前有序地运行一趟检查,并返回单一裁决 —— 假设、路由、影响、范围、记忆和验证。" +--- + +**认知基座** —— 在模型编辑代码_之前_运行的层。`forge substrate ""`(以及 MCP 工具 `substrate_check`)有序地运行一趟检查并返回单一裁决。它把可单独调用的各阶段 —— `preflight`、`route`、`atlas`、`impact`、`reuse`、`context`、`scope`、`lean`、`anchor`、`verify` —— 合成一份预动作契约。 + +```mermaid +flowchart TD + RE["referenced entities"] --> INTAKE + subgraph INTAKE["intake"] + direction LR + PF["preflight · assumption gap"] --> RT["route · cheapest tier"] + end + INTAKE --> ANALYSIS + subgraph ANALYSIS["analysis"] + direction LR + AT["atlas · code graph"] --> IM["impact · blast radius"] --> PT["predict · failing tests"] --> RU["reuse · cache hit?"] + end + ANALYSIS --> SAFETY + subgraph SAFETY["safety + fit"] + direction LR + CX["context · completeness gate"] --> SC["scope · coupled files"] --> ME["memory · recall + lessons"] --> MN["minimality · lean footprint"] --> GA["goal-anchor · drift check"] + end + SAFETY --> VD["verdict"] +``` + +## 三个阶段 + + + + **preflight** 找出假设缺口 —— 任务提到、但仓库未定义的东西。**route** 挑出性价比最高、能胜任的模型层级。 + + + **atlas** 读取代码图,**impact** 计算爆炸半径,**predict** 点名可能失败的测试,**reuse** 检查是否命中已验证缓存。 + + + **context** 运行完整性门,**scope** 浮出耦合文件,**memory** 注入 recall + 经验,**minimality** 衡量 lean 足迹,**goal-anchor** 检查漂移。 + + + +## 爆炸半径 + +**爆炸半径** —— 一次编辑被预测会影响的文件集合,来自代码图。`forge impact` 计算它;流水线在模型触碰任何东西之前把它浮出来。 + +```bash +forge impact verifyToken # predicted impacted files for a symbol +forge impact src/auth.js # …or for a file +``` + +## 默认建议模式 + +裁决**默认是建议性**的 —— 它只报告,不阻断。设置 `FORGE_ENFORCE=1` 可以把最强的信号变成硬阻断: + + + + preflight 找不到可行的意图 —— 任务规格不足。 + + + 完整性门无法覆盖预测的编辑集合。 + + + 受影响集合超过默认的约 25 文件阈值。 + + + +其他一切都留作可以由人覆盖的警告。 + + + 在 Claude Code 上,整个门通过 `UserPromptSubmit` 钩子在**每个 prompt 上自动运行** —— 对干净任务保持静默。`forge substrate "" --json` 提供机器可读的裁决用于脚本化。 + + +## 运行它 + +```bash +forge substrate "Change verifyToken in src/auth.js to require length > 20; update tests" +forge substrate "" --json +``` + +如果裁决为 `ASK FIRST`,在编辑前先提出返回的 `assumption.questions` —— 不要猜规格不足的任务。从推荐的 `route.tier` 开始,只有当外部验证器失败之后再升级,永远不要预防性升级。 + + + 记忆阶段从携证账本中读取。 + diff --git a/mintlify/zh-CN/concepts/proof-carrying-memory.mdx b/mintlify/zh-CN/concepts/proof-carrying-memory.mdx new file mode 100644 index 0000000..0860ac1 --- /dev/null +++ b/mintlify/zh-CN/concepts/proof-carrying-memory.mdx @@ -0,0 +1,95 @@ +--- +title: "携证记忆" +description: "每一条被存下的事实、经验或复用产物都是一个自带证据的声明 —— 只有当独立裁决方把它的置信度抬升到阈值之上时才被信任。" +--- + +**携证记忆 (PCM)** —— 每一条被存下的事实、经验或复用产物都是一个自带证据的_声明_。只有当独立裁决方(测试、CI、人类的接受/回滚)把它的置信度抬升到阈值之上时,它才会被信任。错误的经验会衰减而不是固化。 + + + "携证记忆"是我们对**有证据引用、以内容寻址的记忆**的称呼 —— 声明由其内容的哈希寻址,并链接到支持它的裁决方结果。"证明"是那条证据链加上置信度规则,**不是**形式化机器验证过的证明;流程中不存在定理证明器。 + + +## 一个存储,多个写入者 + +所有记忆子系统都汇聚到同一个存储。`recall`、`remember`/`brain`、`cortex` 经验、`reuse` 产物、以及死循环的 `diagnose` 结果都会以内容寻址的方式把声明写入 `.forge/ledger/`。 + +```mermaid +flowchart LR + subgraph EV["local events"] + direction TB + E1["recall / remember"] + E2["cortex lesson"] + E3["reuse mint"] + E4["diagnose"] + end + EV -->|"content-addressed claims"| LG["(.forge/ledger)"] + O["independent oracles · tests · CI · human accept/revert"] -->|"append evidence · move confidence"| LG + TM["teammate ledgers"] <-->|"git union-merge · conflict-free"| LG + LG --> RV["merged read view · recall list · lesson inject · brain index"] +``` + +## 为什么它能无冲突地收敛 + +因为一个声明的字节是 `(kind, body, scope)` 的纯函数,每个副本计算出的身份都一样 —— 所以队友的账本可以通过纯 git 无冲突地合并。 + +机制上: + +- **证据与墓碑都是只追加的**,并做哈希去重。 +- **置信度 (`val`)** 是一个带衰减的 Beta 后验,只能由裁决方推动。 +- **合并是一个 join-semilattice** —— 已被属性测试验证为可交换、可结合、幂等 —— 因此账本无论以何种顺序合并都能收敛。 + + + `forge init` 会生成账本需要的 union-merge `.gitattributes` 规则;`forge ledger merge ` 可以合并任意另一棵账本树。完整决策见 ADR-0006(携证记忆)。 + + +## 只有裁决方能移动置信度 —— 其他任何东西都不行 + +只有独立的裁决方能移动一条记忆的置信度: + + + + 一次通过、能演练该声明的测试会提升它的置信度。 + + + 一次绿色的流水线是该声明仍然成立的独立证据。 + + + 显式的接受或者回滚是最强的信号。 + + + +无法验证的证据会被一张封闭的 `ORACLES` 表 (`src/ledger.js`) 拒绝。未经审阅的知识衰减为_不确定_,而不是删除 —— 沉睡的声明保留下来供审计,永远不会被静默移除。 + +## 账本表面 + +```bash +forge ledger stats # what the repo knows, by kind and trust level +forge ledger verify # re-check claims are in normal form +forge ledger show # a claim and its evidence trail +forge ledger blame # who minted it, every oracle outcome, per-author trust +forge ledger query "" # retrieve claims by relevance +forge ledger ratify # human accept +forge ledger retract # tombstone a claim +forge ledger merge # fold a teammate's ledger in, conflict-free +forge ledger import # bridge legacy stores into the ledger +``` + +加 `--personal` 使用每用户级别的账本。 + +## 复用缓存也是携证的 + +`forge reuse` 是一个携证的代码缓存。一段生成的产物只有在其证据仍然成立时才会被再次服务 —— 置信度在阈值之上**并且**它的 atlas 依赖仍然可解析。否则就会穿透到生成流程,并在返回途中铸一条新声明。 + +```mermaid +flowchart LR + SP["spec"] --> FP["fingerprint · MinHash + LSH"] + FP --> LD["match ladder · exact to near to adapt to miss"] + LD --> GT{"confidence >= floor AND deps resolve?"} + GT -->|"yes"| SV["serve · proof holds"] + GT -->|"miss"| GN["generate"] + GN -->|"mint claim"| MT["(.forge/ledger)"] +``` + + + MinHash 的近似匹配在非常短的 spec 上偏弱。可选的嵌入后端 (`FORGE_EMBED`) 可以提升这一点;MinHash 仍是零依赖的默认。 + diff --git a/mintlify/zh-CN/concepts/verification-gates.mdx b/mintlify/zh-CN/concepts/verification-gates.mdx new file mode 100644 index 0000000..332b91b --- /dev/null +++ b/mintlify/zh-CN/concepts/verification-gates.mdx @@ -0,0 +1,83 @@ +--- +title: "验证门" +description: "独立验证、幻觉符号标记、规约即契约、skill 门 —— 这些你可以运行的检查会降低但不认证正确性。" +--- + +没有可运行的检查(测试、构建退出码、截图),就不算"完成"。Forge 的每一道验证门都多接住一次。若每任务的漏检率是 `1 − p`、门的捕获率是 `c`,那么静默漏检降到 `(1 − p)(1 − c)`,而这里的每一道门都是多一个 `c`。 + + + **验证是减少而不是认证。** Crew 验证者和幻觉符号标记降低审查负担;它们不证明代码正确。测试和人工修正始终最优先。 + + +## 独立验证 —— `forge verify` + +一道独立的门:它运行仓库真正的测试,标记幻觉符号,并检查溯源。 + +```bash +forge verify # tests + hallucinated-symbol + provenance +forge verify --deep # multi-lens consensus — several independent checks must agree +``` + + + `--deep` (v0.19+) 升级为多镜头共识:该变更必须通过多个独立的验证镜头,而不只是一个。 + + +## 幻觉符号标记 —— `forge atlas has` + +`forge atlas has ` 是幻觉检查:如果模型调用了一个不在代码图中的符号,这道门会标记它。 + +```bash +forge atlas build # index this repo's symbols → .forge/atlas.json +forge atlas has useAuth # "not found" = likely hallucinated +``` + +atlas 特意采用纯 JSON —— Codex、Cursor、Gemini 和 Aider 都可以通过 CLI 或纯 `jq` 读取 `.forge/atlas.json`,消费端无需 MCP 依赖。 + +## 规约即契约 —— `forge spec` + +把行为绑定到一份规约并检测漂移: + +```bash +forge spec init # scaffold an OpenSpec contract +forge spec lock # lock the current spec as the contract +forge spec check # report drift against the locked contract +``` + +## skill 门 —— `forge scan` + +在安装 skill 或 MCP 服务器之前审查其是否存在注入、RCE 或泄露风险: + +```bash +forge scan +``` + + + 一次干净的扫描**不是安全认证**。内置启发式只捕获已知攻击形态(critical)和一部分高严重度模式;通过意味着_"未检测到关键签名"_,而不是_"可以安全安装"_。始终自己审阅源码、权限、包溯源和网络行为。一个**高**严重度发现即便不硬阻断,也不会被标记为安全。外部扫描器是可选加装,除非你启用,否则不会发起网络调用。 + + +## 加固 —— `forge harden` + +接入把密钥和不安全变更挡在门外的安全控制: + +```bash +forge harden # gitleaks pre-commit + sandbox settings +``` + +## 提交级门 —— `forge precommit` + + + `forge precommit` (v0.19+) 是一道提交级门 —— 在 commit 时运行验证底线,以便在部分或未验证的工作落库之前捕获它们。 + + +## UI 检查 —— `forge uicheck` + +确定性 UI 检查,前三个镜头不用 LLM 也不用截图: + +```bash +forge uicheck contrast # WCAG contrast ratio +forge uicheck fingerprint # deterministic design fingerprint +forge uicheck design # slop-distance + conformance gate +forge uicheck visual # Playwright-rendered check (opt-in tier) +``` + +搭配 `forge taste` 选一个视觉方向(brutalist、corporate、editorial、minimalist、playful)并参数化 `design` 门的阈值。 diff --git a/mintlify/zh-CN/guides/radar-deps.mdx b/mintlify/zh-CN/guides/radar-deps.mdx new file mode 100644 index 0000000..883750e --- /dev/null +++ b/mintlify/zh-CN/guides/radar-deps.mdx @@ -0,0 +1,54 @@ +--- +title: "用 radar 保持依赖时效" +description: "forge radar 按时效性把依赖分组到同心圆里,让陈旧或漂移的依赖在咬人之前浮现。" +--- + + + `forge radar` 正在 v0.19 系列中落地。本指南描述它如何契合既有的依赖时效性纪律;请运行 `forge --help` 以确认你所安装版本中的可用性。 + + +Forge 的一条工程规则是:_在添加依赖之前,从实时来源核实当前最佳选项,并优先使用项目已经用了的东西。_ `forge radar` 让依赖的当前状态可见,让这条规则有数据可依。 + +## 思路:时效同心圆 + +`forge radar` 按当前程度把项目的依赖分组到同心的**时效圆**里 —— 从中心的最新到边缘的陈旧或漂移。读这些环是回答"我们让什么漂移了?"最快的方法,不需要手工审计每个包。 + +```bash +forge radar +``` + +## 依赖清单来自哪里 + +Radar 基于与 `forge stack` 相同的清单读取逻辑,后者从依赖清单中检测仓库的真实技术栈: + +```bash +forge stack # languages, frameworks, package managers, real test commands +``` + +由于检测是数据驱动的、且跨生态(`package.json`、`pyproject.toml`、`go.mod`、`Cargo.toml`、`Gemfile`、`composer.json`、`pom.xml` / `build.gradle`、`*.csproj`)都失败开放,radar 可以对 `stack` 理解的同一批清单进行时效性推理。 + +## 在循环中使用它 + + + + 在添加或升级依赖之前,运行 `forge radar` 看看已经有哪些依赖在漂移。 + + + 如果一个能胜任、且当前的依赖已经在内圈里,就复用它,而不是再引入一个新依赖 —— 最小的贴合改动获胜。 + + + 当你确实要升级或替换一个依赖时,记下原因: + ```bash + forge decide "bump to — " + ``` + 这样未来会话读到这个选择,而不是重新争论一遍。 + + + + + Radar 报告时效性,不替你升级。把它的环当作给人类决策的建议性输入 —— 并在称之为"完成"之前用仓库真实的测试 (`forge verify`) 校验任何一次升级。 + + + + 依赖升级之后,运行 Quality 门 —— `forge verify` 和 `forge precommit`。 + diff --git a/mintlify/zh-CN/guides/team-memory.mdx b/mintlify/zh-CN/guides/team-memory.mdx new file mode 100644 index 0000000..f367581 --- /dev/null +++ b/mintlify/zh-CN/guides/team-memory.mdx @@ -0,0 +1,66 @@ +--- +title: "用账本做团队记忆" +description: "通过纯 git 无冲突地合并队友的账本 —— 没有服务器、没有同步服务,只是以任意顺序都能收敛的文件。" +--- + +基座学到的一切 —— cortex 经验、`forge remember` 事实、已验证的复用产物 —— 都作为内容寻址的声明落在一个 git 原生的账本 (`.forge/ledger/`) 里,天生按无冲突方式合并。没有服务器,也没有同步服务;只是 git 中的文件。 + +## 三条命令搞定团队记忆 + + + + ```bash + forge init + ``` + 这会生成账本需要的 `.gitattributes` union-merge 规则等内容。 + + + Cortex 经验和 `forge remember` 事实会在你工作时把声明影子写入账本 —— 没有额外命令要跑。 + + + ```bash + git pull && forge ledger merge + ``` + 任意顺序 —— 合并是无冲突的。 + + + +## 为什么它不会冲突 + +一条声明的字节是 `(kind, body, scope)` 的纯函数,所以每个副本对同样的知识都会算出同样的身份。合并是一个 join-semilattice —— 已被属性测试验证为可交换、可结合、幂等 —— 所以两个队友的账本无论谁先同步都会收敛到同样的状态。 + +```mermaid +flowchart LR + A["your ledger"] <-->|"git union-merge · conflict-free"| B["teammate ledger"] + A --> M["merged read view"] + B --> M + M --> R["recall list · lesson inject · brain index"] +``` + + + 独立铸出的相同知识会收敛为**一条**声明,并在其溯源中保留每一位作者。 + + +## 信任与溯源 + +置信度只能被独立的裁决方 —— 测试、CI、人类的接受/回滚 —— 移动,所以导入队友的账本并不盲目相信他们的笔记;它导入的是他们的_证据_。 + +```bash +forge ledger blame # who minted a claim, every oracle outcome, per-author trust +forge ledger stats # the merged view, by kind and trust level +forge ledger verify # confirm every claim is in normal form +``` + +## 团队范围内的复用 + +一旦队友的已验证代码进入合并后的账本,你就可以带着它的证据复用它: + +```bash +forge reuse query "" +``` + +命中会指向可运行、经测试确认的代码,以及能证明它的 `forge ledger blame` —— 复用它,而不是重新生成。 + + + 沉睡的声明保留下来供审计,永远不会被删除;未经审阅的知识衰减为_不确定_,而不是被删除。账本是一条证据链,不是一个可以静默丢失的缓存。 + diff --git a/mintlify/zh-CN/guides/zero-config-onboarding.mdx b/mintlify/zh-CN/guides/zero-config-onboarding.mdx new file mode 100644 index 0000000..225a228 --- /dev/null +++ b/mintlify/zh-CN/guides/zero-config-onboarding.mdx @@ -0,0 +1,80 @@ +--- +title: "引导式、低配置上手" +description: "五分钟进入生产:安装一次,配置仓库一次,做一个任务,然后在第二天看到账本开始发挥效益 —— 引导式、低配置,不是零操作。" +--- + +Forge 目标是**引导式、低配置上手** —— 一个新仓库通常在大约五分钟内就能投入使用。安装一次、配置仓库一次、做一个任务,然后账本在第二天开始发挥效益。(是低配置,不是零配置:你仍然要安装 CLI、在每个仓库运行 `forge init`,并且某些路径假定有 Bash、Git 和 `jq`。) + +```mermaid +flowchart TD + I["forge init"] --> Cfg["every tool configured from one source"] + Cfg --> Work["you work as usual"] + Work --> Gate["substrate checks each task · ask first? · which model? · what breaks?"] + Gate --> Edit["agent edits, with guardrails"] + Edit --> Learn["cortex learns from corrections"] + Learn -.->|next task is smarter| Work +``` + +## 1. 安装(一次) + +推荐路径不需要令牌也不需要克隆: + + + +```bash Plugin +/plugin marketplace add CodeWithJuber/forgekit +/plugin install forgekit +``` + +```bash CLI +npm install -g @codewithjuber/forgekit +``` + + + +```bash +forge doctor # everything green? +``` + +## 2. 配置一个仓库(每个仓库一次) + +```bash +cd ~/your-project +forge init # emits AGENTS.md, CLAUDE.md, .gemini/settings.json, .aider.conf.yml … +``` + +现在 Claude Code、Codex、Cursor、Gemini、Aider、Copilot、Windsurf、Zed 和 Continue 都从各自的原生文件读取**同样的**规则。以后修改规则,编辑 `source/rules.json`(或放一个仓库级的 `.forge/rules.json`),然后运行 `forge sync`。 + +## 3. 使用认知基座 + +```bash +forge substrate "" # ask/route/impact/scope/reuse/context/memory/verify in one pass +forge substrate "" --json +forge impact # the blast radius on its own +``` + +如果 `forge substrate` 返回 `ASK FIRST`,在编辑前先提出返回的问题。 + +## 4. 使用附加功能 + +```bash +forge atlas build # index this repo's symbols → .forge/atlas.json +forge atlas query useAuth # where is it defined? +forge atlas has useAuth # does it exist? "not found" = likely hallucinated +forge recall add "db port" "Postgres is on 5433 here, not 5432" +forge catalog # the Start-Here index of everything +``` + +## 5. 第二天:账本开始学习 + +第一天基座学到的一切 —— cortex 经验、被记住的事实、已验证的代码 —— 都作为声明落在 `.forge/ledger/` 中。 + +```bash +forge ledger stats # what the repo knows, by kind and trust level +forge ledger blame # who minted a claim, every oracle outcome +forge reuse query "" # verified code you already have +``` + + + 下一步:通过纯 git 无冲突地合并队友的账本。 + diff --git a/mintlify/zh-CN/installation.mdx b/mintlify/zh-CN/installation.mdx new file mode 100644 index 0000000..1458b09 --- /dev/null +++ b/mintlify/zh-CN/installation.mdx @@ -0,0 +1,98 @@ +--- +title: "安装" +description: "同一棵树上的三扇门:plugin marketplace、npm 全局安装、以及无需 registry 的 github: 安装 —— 外加贡献者用的符号链接开发环境。" +--- + +Forge 遵循**一棵树、三扇门**的设计:plugin manifest、加固安装脚本和 npm bin 都指向同一份 `global/` + `source/` 树。根据你的工具挑一个通道即可。 + +## 选择一个通道 + + + + 面向 Claude Code 和 Codex。护栏自动接线,无需合并。 + + + 面向任何工具。从公共 npm registry 安装 `forge` CLI。 + + + 无需 registry —— 直接从仓库安装。 + + + 克隆 + `npm link`,或运行 `bash install.sh` 建立符号链接。 + + + +## 要求 + +- **Node.js >= 20** +- **零运行时依赖** —— 一切都是 Node 内置模块。可选层(`FORGE_EMBED` 嵌入,`uicheck visual` 需要的 Playwright)是可选加装,不引入必需依赖。 + +## Plugin marketplace + +面向 Claude Code 和 Codex 的推荐路径,不需要令牌也不需要克隆: + +```bash +/plugin marketplace add CodeWithJuber/forgekit +/plugin install forgekit +``` + +Plugin 通过 `${CLAUDE_PROJECT_DIR}` 接入护栏,使预动作门与完成门在后台生效。 + +## npm 全局 + +从公共 npm 安装,可服务任何工具: + +```bash +npm install -g @codewithjuber/forgekit +forge doctor # everything green? +``` + +## 无 registry 的 github: 安装 + +```bash +npm install -g github:CodeWithJuber/forgekit +``` + +## 贡献者 / 本地开发 + + + +```bash npm link +git clone https://github.com/CodeWithJuber/forgekit.git +cd forgekit +npm link +``` + +```bash install.sh (symlink setup) +git clone https://github.com/CodeWithJuber/forgekit.git +cd forgekit +bash install.sh +``` + + + +这个安装脚本经过加固:幂等、基于符号链接、带备份,不使用 `curl | sh`。 + +## 校验 + +无论走哪个通道,都可以确认安装: + +```bash +forge doctor # tools, guards, MCP auth, config drift, update status +``` + + + `forge doctor` 还会为 git 检出显示一条不烦人的"落后于上游几个提交"提示。设置 `FORGE_NO_UPDATE_CHECK=1` 可以静默它。每一条路径都失败开放 —— 离线或 detached HEAD 报告"unknown",从不作为错误。 + + +## 保持 Forge 最新 + +```bash +forge update --check # report whether a newer version is available +forge update # apply the update (git checkout or npm/copy install) +forge update --to # pin or downgrade to a specific version +``` + + + 转到快速开始,运行 `forge init` 并进行你的第一次基座检查。 + diff --git a/mintlify/zh-CN/introduction.mdx b/mintlify/zh-CN/introduction.mdx new file mode 100644 index 0000000..739bfa8 --- /dev/null +++ b/mintlify/zh-CN/introduction.mdx @@ -0,0 +1,99 @@ +--- +title: "简介" +description: "Forge 是每个无状态模型都缺失的认知基座 —— 记忆、前瞻与护栏 —— 以原生配置的形式交付给每一个 AI 编码代理。" +--- + +**为每一个 AI 编码代理提供同一个大脑。** 大语言模型是无状态的:一个上下文窗口,每次调用都被清空。它不记得团队学到过什么,不预知一次编辑会破坏什么,也没有强制执行的护栏。Forge +(`@codewithjuber/forgekit`) 就是**认知基座** —— 一个在模型编辑代码_之前_运行的层,负责提供有证据引用的、以内容寻址的记忆(我们称之为"携证记忆"),启发式的影响前瞻,以及强制执行的护栏 —— 再加上一个 +**跨工具的配置编译器**,把这个大脑作为原生配置一次性交付到每一个工具中。Claude Code 是测试最深入的集成;其他工具会收到原生配置和 MCP 工具,但实际使用中打磨得较少。 + + + + 携证记忆,跨会话和跨队友持续存在。每一条经验、事实和已验证的复用都是一个自带证据的声明。 + + + 一次编辑的爆炸半径 —— 从代码图中读取的、被预测将会触及的文件集合,包括你从未点名的耦合文件。 + + + 确定性的钩子强制执行模型永远不能违反的规则。它们能挺过一次上下文压缩,而配置文件里的散文规则做不到。 + + + +## 问题 + +大语言模型是无状态的 —— 一个上下文窗口,每次调用都被清空。 + +- 它**没有记忆**,不知道团队已经学到过什么。 +- 它**没有前瞻**,不知道一次编辑会破坏什么。 +- 它**没有强制护栏** —— 散文形式的规则在一次压缩后就被遗忘。 + +而每个工具都要自己的配置文件(`CLAUDE.md`、`AGENTS.md`、`.cursor/rules`、`GEMINI.md`、MCP……)。Forge 就是那个认知基座,补齐这三件缺失的事,并且用一个编译器从单一源交付给每一个工具。 + +## 论点 + +模型无法在两次调用之间从你的代码库中学习:它的权重被冻结,工作记忆在每次回答后被清空。记忆、前瞻和自检无法通过提示词植入模型 —— 它们必须从_外部_供给。这个外部的层就是认知基座。形式化地说,推理是一个固定函数 `y = f(x)`,调用之间没有状态;Forge 就是那个状态。 + + + + 把你的规则和基座默认值写在一个规范源中 + (`source/rules.json`、`source/substrate.json`、`source/mcp.json`)。 + + + `forge sync` 把这个源编译为每个工具的原生配置 —— 九个 AI 编码工具外加 MCP —— 并加上内容哈希头,因此漂移可检测,重复运行是无操作的。 + + + `forge substrate ""` 运行一次确定性的预动作检查:假设、路由、复用、上下文、爆炸半径、范围以及目标锚点。 + + + 只有独立的裁决方 —— 测试、CI、人类的接受/回滚 —— 才能改变记忆的置信度,因此错误的经验会衰减而不是固化。 + + + +## 你能得到什么 + +- **跨会话、跨队友持续存在的记忆。** 每一条经验、事实和已验证的复用都是_携证记忆 (PCM)_ —— 我们对有证据引用、以内容寻址的记忆的称呼:一个携带其证据引用的声明,只有当独立裁决方把它的置信度抬升到阈值以上时才会被信任。"证明"指的是那条证据链,而不是形式化证明。 +- **在你破坏东西之前预知。** 询问"修改 `verifyToken` 会破坏什么?",从代码图得到爆炸半径,包括你从未点名的耦合文件。 +- **不会被遗忘的护栏。** 确定性钩子强制执行保护路径、成本预算和死循环检测 —— 它们能挺过一次上下文压缩。 +- **端到端能收尾的工作。** 一个完成门在每次会话中最多阻断一次:当代码变更了但没有对应的文档或状态产物跟进时,阻断的原因就是修复清单。 +- **一份配置服务 9 个工具。** 一次编写规则;Forge 生成每个工具的原生配置,外加给 Roo 和 VS Code 的 MCP。零运行时依赖 —— 一个 Node CLI、纯文本文件放在 git 里,没有服务器。 + +## Forge 会喂给哪些工具? + +Forge 为**九个工具**生成配置,并提供一个用于 Roo Code 与 VS Code 的 MCP 服务器: +Claude Code、Codex、Cursor、Gemini、Aider、Copilot、Windsurf/Devin、Zed 和 Continue。 +每一个都从自己的原生文件读取同样的规则。 + +## 诚实的边界 + +Forge 到处标明自己的天花板。 + + + Forge **减少但不消除**规则漂移。它是一层透明度和可靠性,不是测试、审查或判断的替代品。 + + +- **护栏只强制那些可以表达为钩子的东西**(路径、格式、diff 大小、预算)。语义规则("倾向函数式")仍然是散文,有时会被忽略。 +- **验证是减少而不是认证。** Crew 验证者和幻觉符号标记降低了审查负担;它们不证明代码正确。 +- **没有权重级学习。** `recall` / `cortex` 只是文件和提示词记忆 —— 没有 RL,没有微调。 +- **影响图是基于正则表达式的近似** —— 保守估计,而不是精确的调用图。 +- **测试和人工修正始终最优先。** + + + Forge 处于 **beta**。核心部分(`init`、`sync`、`substrate`、`impact`、`ledger`、护栏)经过测试并每日使用;部分参数在 `1.0` 之前可能变动。 + + +## 下一步 + + + + 安装、运行 `forge init`,并让你的第一个任务通过基座。 + + + 四层编译器、携证记忆和预动作门。 + + + 每个命令,按 Core、Memory、Substrate、Quality 和 Config 分组。 + + + 通过纯 git 无冲突地合并队友的账本。 + + diff --git a/mintlify/zh-CN/quickstart.mdx b/mintlify/zh-CN/quickstart.mdx new file mode 100644 index 0000000..5d7d931 --- /dev/null +++ b/mintlify/zh-CN/quickstart.mdx @@ -0,0 +1,97 @@ +--- +title: "快速开始" +description: "安装 Forge、从单一源生成每个工具的配置、并运行你的第一个预动作门 —— 大约 60 秒。" +--- + +从零到配置完成的仓库和第一次基座检查,只需要大约一分钟。 + +## 1. 安装 + + + +```bash Plugin (Claude Code / Codex) +/plugin marketplace add CodeWithJuber/forgekit +/plugin install forgekit +``` + +```bash npm (any tool) +npm install -g @codewithjuber/forgekit +``` + +```bash No registry +npm install -g github:CodeWithJuber/forgekit +``` + + + +对于 Claude Code 和 Codex,推荐使用 plugin 方式 —— 护栏会自动接线,无需手动合并。完整的安装矩阵(包括符号链接开发环境)见 [安装](/zh-CN/installation)。 + +## 2. 配置一个仓库 + + + + ```bash + cd ~/your-project + forge init + ``` + 这会生成 `AGENTS.md`、`CLAUDE.md`、`.gemini/settings.json`、`.aider.conf.yml` 等 —— 外加账本需要的 `.gitattributes` union-merge 规则。Claude Code、Codex、Cursor、Gemini、Aider、Copilot、Windsurf、Zed 和 Continue 现在都从各自的原生文件读取**同样的**规则。 + + + ```bash + forge doctor + ``` + 对已安装工具、护栏、MCP 认证和配置漂移进行通过/失败检查。 + + + 编辑 `source/rules.json`(或放一个仓库级的 `.forge/rules.json`),然后重新编译: + ```bash + forge sync + ``` + `sync` 是幂等的 —— 只重写发生了变化的内容。 + + + +## 3. 运行预动作门 + +基座是在模型编辑代码_之前_运行的层。一条命令就能运行整个门: + +```bash +forge substrate "Change verifyToken in src/auth.js to require length > 20; update tests" +# → assumption verdict · cheapest capable model · predicted blast radius +# (including files you didn't name) · scope clusters · verification checklist +``` + + + 在 Claude Code 上,基座通过 `UserPromptSubmit` 钩子在**每个 prompt 上自动运行** —— 仅作建议,对干净任务保持静默。其他每个工具都会获得一条原生配置规则,加上它可以自己调用的 19 个 MCP 工具。 + + +如果 `forge substrate` 返回 `ASK FIRST`,在编辑前先提出返回的问题。在任何变更之前,阅读预测的受影响文件 —— 也就是爆炸半径。 + +```bash +forge substrate "" --json # machine-readable verdict +forge impact # the blast radius on its own +``` + +## 4. 探索附加功能 + +```bash +forge atlas build # index this repo's symbols → .forge/atlas.json +forge atlas query useAuth # where is it defined? (cheaper than grep-and-read) +forge atlas has useAuth # does it exist? "not found" = likely hallucinated +forge recall add "db port" "Postgres is on 5433 here, not 5432" +forge catalog # the Start-Here index of everything +``` + +## 5. 第二天:账本开始学习 + +第一天基座学到的一切都作为声明落在 `.forge/ledger/` 中。这就是携证记忆 —— 现在它开始发挥效益: + +```bash +forge ledger stats # what the repo knows, by kind and trust +forge ledger blame # who minted a claim, every oracle outcome +forge reuse query "" # verified code you already have +``` + + + 阅读预动作门如何把各阶段合成为单一裁决。 + diff --git a/mintlify/zh-Hans/cli/config.mdx b/mintlify/zh-Hans/cli/config.mdx new file mode 100644 index 0000000..3e3d3ce --- /dev/null +++ b/mintlify/zh-Hans/cli/config.mdx @@ -0,0 +1,86 @@ +--- +title: "Config 命令" +description: "提供方、成本、仪表盘、品牌、atlas、stack:config、cost、dash、brand、atlas、stack——外加 v0.19+ 的 report 与 tools 命令。" +--- + +Config 分组覆盖提供方、可观察性、代码图和技术栈检测。 + +## `forge config` + +提供方配置——展示 / 切换 / 添加提供方,设置默认模型。 + +```bash +forge config # 显示当前配置 +forge config switch +forge config add +``` + +## `forge cost` + +通过实测的阶段系数计算的真实每日花销。 + +```bash +forge cost # 真实的每日花销 +forge cost --stages # 实测的每阶段成本系数 +``` + + + **仅报告已实测的阶段**——没有事件的阶段会显示 “no data”,绝不使用默认值。 + + +## `forge dash` + +对 ledger、指标与爆炸半径的本地仪表盘。 + +```bash +forge dash # 仅本机、只读(默认端口 4242) +``` + +## `forge brand` + +打印当前生效的品牌 token 映射。 + +```bash +forge brand +``` + +品牌以单个 token(`brand.json`)存储;换品牌只需一次编辑。 + +## `forge atlas` + +构建 / 查询代码图。 + +```bash +forge atlas build [path] # 遍历目录树 → .forge/atlas.json +forge atlas query "what calls Z" +forge atlas has # 幻觉符号检查 +``` + +atlas 是纯 JSON——任何工具都能读,不需要 MCP。 + +## `forge stack` + +从清单文件检测本仓库的真实技术栈。 + +```bash +forge stack +``` + +读取 `package.json`、`pyproject.toml`、`go.mod`、`Cargo.toml`、`Gemfile`、 +`composer.json`、`pom.xml` / `build.gradle` 和 `*.csproj`,并报告语言、框架、包管理器,以及仓库**实际**的测试命令——这些会喂进基座的验证清单。 + +## `forge report` v0.19+ + +生成本仓库 Forge 状态的静态 HTML 报告——把 ledger、指标和爆炸半径渲染成一个自包含文件,可分享或归档。 + +```bash +forge report +``` + +## `forge tools` v0.19+ + +选择本仓库的主用 AI 编码工具,并接线相应的 `.gitignore` 条目,让生成的配置与 `.forge/` 产物按你的设置被正确忽略。 + +```bash +forge tools +``` diff --git a/mintlify/zh-Hans/cli/core.mdx b/mintlify/zh-Hans/cli/core.mdx new file mode 100644 index 0000000..b20b380 --- /dev/null +++ b/mintlify/zh-Hans/cli/core.mdx @@ -0,0 +1,70 @@ +--- +title: "Core 命令" +description: "引导与维护一个仓库:init、sync、doctor、catalog、docs 和 update。" +--- + +Core 分组负责引导一个仓库并保持它健康。 + +## `forge init` + +搭建本仓库的配置——从一份共享源生成每个工具的配置。 + +```bash +forge init +``` + +生成 `AGENTS.md`、`CLAUDE.md`、`.gemini/settings.json`、`.aider.conf.yml` 等 +(以及给 Roo Code 和 VS Code 的 MCP 服务器配置),外加 ledger 所需的 `.gitattributes` union-merge 规则。 + +## `forge sync` + +把规范源重新编译为每个工具的原生配置文件。 + +```bash +forge sync +``` + +幂等——只会重写发生变化的部分。编辑 `source/rules.json` 或仓库内的 `.forge/rules.json` 之后运行它。 + +## `forge doctor` + +对已安装工具、护栏、MCP 授权和配置漂移做健康检查。 + +```bash +forge doctor +``` + +在工具、护栏、MCP 接线、配置漂移与更新状态上给出通过/失败结果。所有路径都是 fail-open。当配置了自定义 gateway 时,一条 **gateway models** 行会打印解析出的 `tier → model` 映射。 + +## `forge catalog` + +Start Here——列出每一个工具、crew 与护栏,并附一句话说明它们的用途。 + +```bash +forge catalog +``` + +## `forge docs` + +文档 ↔ 代码漂移。 + +```bash +forge docs check # 注册表对账——命令、环境变量、MCP 工具、CHANGELOG +forge docs sync # diff 驱动的过期文档清扫 +``` + + + 当命令、环境变量、MCP 工具或 CHANGELOG 与代码发生漂移时,`docs check` 会让 CI 失败。`docs sync` 会扫过 diff 并报告 UPDATED / STALE / VERIFIED-UNAFFECTED。 + + +## `forge update` + +在三种安装模式下进行自更新。 + +```bash +forge update # 应用更新(git checkout 或 npm/copy 安装) +forge update --check # 报告是否有更新可用 +forge update --to # 锁定或回退到特定版本(v0.19+) +``` + +所有路径都是 fail-open——离线、无上游或 detached HEAD 都会返回 “unknown”,绝不会报错。`FORGE_NO_UPDATE_CHECK=1` 可以让 doctor 的提示保持静默。 diff --git a/mintlify/zh-Hans/cli/memory.mdx b/mintlify/zh-Hans/cli/memory.mdx new file mode 100644 index 0000000..dd09dd4 --- /dev/null +++ b/mintlify/zh-Hans/cli/memory.mdx @@ -0,0 +1,103 @@ +--- +title: "Memory 命令" +description: "跨会话与团队记忆:cortex、recall、remember、brain、ledger、reuse、handoff 和 decide——全部汇聚到携证 ledger 上。" +--- + +Memory 分组管理跨会话与团队记忆。它们都汇聚到 `.forge/ledger/` 下的携证 ledger 上。相关模型请见 [携证记忆](/zh-Hans/concepts/proof-carrying-memory)。 + +## `forge cortex` + +自我纠错的项目记忆——从更正中挖掘出的经验。 + +```bash +forge cortex status # 学到了什么 +forge cortex why # 为什么这条经验在这里适用 +``` + +## `forge recall` + +管理跨会话的个人记忆。 + +```bash +forge recall list # 由 recall-load 护栏在下一次会话中注入的事实 +forge recall add "db port" "Postgres is on 5433 here, not 5432" +forge recall consolidate # 汇总(建议性,人工可复核) +``` + +## `forge remember` + +给本仓库的可移植记忆添加一条持久的、可提交到仓库的事实。 + +```bash +forge remember "" +``` + +## `forge brain` + +显示或重建可移植的项目记忆索引。 + +```bash +forge brain # 显示索引 +forge brain --rebuild # 重建索引 +``` + +## `forge ledger` + +携证记忆——内容寻址的主张存储。 + +```bash +forge ledger stats # 本仓库知道什么,按类别与信任等级列出 +forge ledger verify # 重新校验主张处于范式 +forge ledger show # 一条主张及其证据 +forge ledger blame # 谁写下的、每一次裁决结果、按作者划分的信任度 +forge ledger query "" # 按相关性检索 +forge ledger ratify # 人工接受 +forge ledger retract # 给一条主张打上墓碑 +forge ledger merge # 无冲突并入队友的 ledger +forge ledger import # 把旧存储桥接到 ledger 中 +``` + +加上 `--personal` 使用每用户的 ledger。 + +## `forge reuse` + +携证代码缓存——只在其证据仍然成立时才提供。 + +```bash +forge reuse query "" # 你已拥有的、已验证的代码 +forge reuse mint "" --file # 把一个产物加入缓存 +forge reuse stats # 缓存统计 +``` + +## `forge handoff` + +有边界的会话快照——重写 `.forge/state.md`,在每次会话开始时被重新注入。 + +```bash +forge handoff "" --next "" +``` + +## `forge decide` + +仅追加的决策日志——`.forge/decisions.md` 中的 `D-####` 精简 ADR 条目。 + +```bash +forge decide " — " +forge decide # 在重新决策前先读一读日志 +``` + +## `forge know` v0.19+ + +把一条事实路由到其正确的存储归宿——判断一段知识应放在 `recall`、`remember`/`brain`、决策或 cortex 经验中,并把它归档到那里。 + +```bash +forge know "" +``` + +## `forge deja` v0.19+ + +相似过往工作查询——在 ledger 里浮现出与你即将开始的工作相似的历史,让你复用现有的证明而不是重新生成。 + +```bash +forge deja "" +``` diff --git a/mintlify/zh-Hans/cli/overview.mdx b/mintlify/zh-Hans/cli/overview.mdx new file mode 100644 index 0000000..8a9ad1e --- /dev/null +++ b/mintlify/zh-Hans/cli/overview.mdx @@ -0,0 +1,55 @@ +--- +title: "CLI 概览" +description: "每一个 forge 命令,按 Core、Memory、Substrate、Quality 和 Config 分组——命令面本身是数据,通过严格的漂移检查与文档相互对账。" +--- + +`forge` 命令面被定义为数据(`src/commands.js`),并由 `forge docs check` 与文档对账,因此一个命令无法在不被文档察觉的情况下上线或消失。命令分为五组。 + + + + 引导与维护:`init`、`sync`、`doctor`、`catalog`、`docs`、`update`。 + + + 跨会话与团队记忆:`cortex`、`recall`、`remember`、`brain`、`ledger`、 + `reuse`、`handoff`、`decide`。 + + + 行动前关卡及其各阶段:`substrate`、`preflight`、`route`、`impact`、 + `scope`、`context`、`anchor`、`diagnose`、`imagine`、`lean`。 + + + 验证与安全:`verify`、`scan`、`spec`、`taste`、`uicheck`、`harden`。 + + + 提供方、成本、仪表盘、品牌、atlas、stack:`config`、`cost`、`dash`、`brand`、 + `atlas`、`stack`。 + + + +## 约定 + +- **默认建议性。** 设置 `FORGE_ENFORCE=1` 可把基座变成对最强信号的硬阻断 + (空洞的提示、无法装配出必需上下文、爆炸半径超过默认的 25 文件阈值)。 +- **默认安静。** 每个命令的 `Forge — …` 标题只是品牌装饰,藏在 + `--verbose` / `FORGE_VERBOSE` 后面;命令会先输出结果。 +- **管道友好的输出。** 被管道时输出纯文本;在 TTY 上会加上品牌配色和置信度进度条。`NO_COLOR` 关掉颜色,`FORCE_COLOR=1` 强制打开。 +- **`--json`** 在基座和大多数分析命令中可用,便于脚本使用。 + + + 运行 `forge --help` 查看始终最新的命令列表,或 `forge catalog` 查看每个工具、crew 与护栏的 Start-Here 索引及一句话说明。 + + +## v0.19+ 的新增内容 + +一些命令和参数正在 v0.19 系列中登陆。它们记录在各自的分组页面里,并在正文标注: + +| 命令 / 参数 | 分组 | 作用 | +| ---------------------- | -------- | ------------------------------------------------- | +| `forge know` | Memory | 把一条事实路由到它正确的存储归宿。 | +| `forge deja` | Memory | 相似的过往工作查询。 | +| `forge precommit` | Quality | commit 级别的验证关卡。 | +| `forge radar` | Quality | 依赖时效性环。 | +| `forge report` | Config | 生成本仓库 Forge 状态的静态 HTML 报告。 | +| `forge tools` | Config | 主用工具选择 + gitignore 接线。 | +| `forge verify --deep` | Quality | 多视角共识验证。 | +| `forge update --to` | Core | 锁定或回退到特定版本。 | diff --git a/mintlify/zh-Hans/cli/quality.mdx b/mintlify/zh-Hans/cli/quality.mdx new file mode 100644 index 0000000..59766bb --- /dev/null +++ b/mintlify/zh-Hans/cli/quality.mdx @@ -0,0 +1,81 @@ +--- +title: "Quality 命令" +description: "验证与安全:verify、scan、spec、taste、uicheck 和 harden——外加 v0.19+ 的 precommit 与 radar 关卡。" +--- + +Quality 分组是验证与安全的入口。这些命令如何组合,请见 [验证关卡](/zh-Hans/concepts/verification-gates)。 + +## `forge verify` + +独立验证关卡——测试 + 幻觉符号 + 溯源。 + +```bash +forge verify +forge verify --deep # 多视角共识(v0.19+) +``` + +## `forge scan` + +技能关卡——在安装前审查一个 skill 或 MCP 服务器是否存在注入 / RCE / 数据外泄风险。 + +```bash +forge scan +``` + +## `forge spec` + +规约即契约——init(OpenSpec)、lock 与漂移检查。 + +```bash +forge spec init +forge spec lock +forge spec check +``` + +## `forge taste` + +为本仓库启用一种 UI 品位工具(不带参数会列出选项)。 + +```bash +forge taste # 列出配置 +forge taste # brutalist · corporate · editorial · minimalist · playful +``` + +写入 `DESIGN.md`,并参数化 `uicheck design` 关卡的阈值。 + +## `forge uicheck` + +确定性 UI 检查。 + +```bash +forge uicheck contrast # WCAG 对比度 +forge uicheck fingerprint # 确定性设计指纹 +forge uicheck design # slop 距离 + 合规关卡 +forge uicheck visual # 基于 Playwright 的渲染检查(可选层) +``` + +## `forge harden` + +接线安全控制——gitleaks pre-commit + 沙箱设置。 + +```bash +forge harden +``` + +## `forge precommit` v0.19+ + +commit 级别关卡——在 commit 时运行验证下限,让部分或未验证的工作在落地前被拦下。 + +```bash +forge precommit +``` + +## `forge radar` v0.19+ + +依赖时效性环——把项目依赖按时效性分组,让陈旧或漂移的依赖在造成问题之前显形。 + +```bash +forge radar +``` + +如何读懂这些环,请见 [保持依赖时效性](/zh-Hans/guides/radar-deps) 指南。 diff --git a/mintlify/zh-Hans/cli/substrate.mdx b/mintlify/zh-Hans/cli/substrate.mdx new file mode 100644 index 0000000..9e43c86 --- /dev/null +++ b/mintlify/zh-Hans/cli/substrate.mdx @@ -0,0 +1,99 @@ +--- +title: "Substrate 命令" +description: "行动前关卡及可单独调用的各阶段:substrate、preflight、route、impact、scope、context、anchor、diagnose、imagine 和 lean。" +--- + +Substrate 分组就是行动前关卡。`forge substrate` 把其余各阶段合成一次裁决;每个阶段也都可以单独调用。管道细节请见 [行动前关卡](/zh-Hans/concepts/pre-action-gate)。 + +## `forge substrate` + +一次行动前关卡:假设、路由、影响、范围、记忆、验证。 + +```bash +forge substrate "" +forge substrate "" --json +``` + +若返回 `okToProceed:false`,在编辑前先问它返回的 `assumption.questions`。 + +## `forge preflight` + +假设检查——任务点名的东西中,仓库还没定义的部分。 + +```bash +forge preflight "" +``` + +## `forge route` + +为任务推荐能胜任的最便宜模型。 + +```bash +forge route "" +forge route gateway # 生成 LiteLLM gateway 配置 +``` + +## `forge impact` + +基于 atlas 图,预测一个符号或文件的爆炸半径。 + +```bash +forge impact +``` + +## `forge scope` + +把文件拆分为独立聚类——外加你未点名的耦合文件。 + +```bash +forge scope +``` + +## `forge context` + +有预算的上下文装配 + 完整性关卡——一次编辑必须知道的信息。 + +```bash +forge context "" +``` + +通过对预测编辑集的 set-cover 装配一份有预算的上下文,应用一条压缩阶梯,并报告计算出的缺失集。 + +## `forge anchor` + +目标漂移检查——你实际的(git)改动是否仍在既定目标上? + +```bash +forge anchor set "" # 让目标跨会话持久保留 +forge anchor show +forge anchor clear +``` + +## `forge diagnose` + +死循环检查——记录一次失败;同一签名出现 3 次将会生成一份诊断 + 升级建议。 + +```bash +forge diagnose "" +``` + +## `forge imagine` + +后果模拟——为任务给出预测的破坏点 + 最小 dry-run 测试套件。 + +```bash +forge imagine "" +forge imagine "" --run # 在沙箱中执行这套最小测试 +``` + +## `forge lean` + +范围最小性(M5)——衡量 diff 的足迹与任务要求之间的差距。 + +```bash +forge lean +``` + + + `route`、`impact`、`scope`、`context`、`anchor` 和 `lean` 各阶段都会在 `forge substrate` 内部运行。想只拿其中一个信号时,单独调用它们。 + diff --git a/mintlify/zh-Hans/concepts/config-compiler.mdx b/mintlify/zh-Hans/concepts/config-compiler.mdx new file mode 100644 index 0000000..45df2a2 --- /dev/null +++ b/mintlify/zh-Hans/concepts/config-compiler.mdx @@ -0,0 +1,84 @@ +--- +title: "四层配置编译器" +description: "只写一次基座;forge sync 把它编译成每个工具的原生配置。四层是大脑的表达方式;编译器是它的交付方式。" +--- + +只写一次基座。`forge sync` 会把这份源编译成每个工具的原生配置。四层是 _大脑如何被表达_;编译器是 _它如何被交付_。 + +```mermaid +flowchart TD + S["source/ · rules.json · substrate.json · mcp.json"] -->|"forge sync — content-hash + DO-NOT-EDIT headers"| N["native configs · CLAUDE.md · AGENTS.md · .cursor · .gemini · .aider"] + S -. configures .-> L + subgraph L["the four layers"] + direction LR + T["tools · model-invoked skills"] + C["crew · isolated sub-agents"] + G["guards · deterministic hooks"] + M["mcp · atlas + substrate server"] + end +``` + +## 一份源,多个生成器 + +规则**只写一次**(`source/rules.json`);一个确定性编译器(`forge sync`)以每个工具的原生格式发出配置,并带内容哈希头,让漂移可检测,重跑是无操作。任何规则都不会被写第二遍。规范源是三个文件: + +| 源文件 | 存放内容 | +| ----------------------- | -------------------------------------------------------------------- | +| `source/rules.json` | 规范的工程规则(git、测试、安全、风格)。 | +| `source/substrate.json` | 认知基座的默认值——阈值、路由、LLM 参数。 | +| `source/mcp.json` | 生成到各工具中的 MCP 服务器定义。 | + +## 四层 + +每一层都有品牌命名,并跨工具发出。 + + + + `~/.forge/tools/` → `~/.claude/skills/`。遵循 + `SKILL.md` 标准(`name` + `description` frontmatter)的模型可调用 skill。 + + + `~/.forge/crew/` → `~/.claude/agents/`。上下文隔离的子代理,如 scout、verifier 和 frontend-verifier。 + + + `~/.forge/guards/` → `settings.json` hooks。**唯一 _强制执行_ 而非建议的一层。** 一条 guard 是模型无法漂移出的确定性钩子。`CLAUDE.md` 里的散文规则会被确认,然后在压缩后遗忘;guard 不会。每一条可强制的不变式都应放在这里。 + + + Forge 附带一个 stdio 服务器(`src/cortex_mcp.js`),暴露 19 个 MCP 工具:基座检查 + (`substrate_check` / `predict_impact` / `assumption_gate` / …)、记忆读 _与_ 写(`forge_remember`、ledger ratify/retract)以及运维/健康接口。 + + + +横切关注点贯穿四层:**atlas**(代码图)、**lean** +(极简性——同时以工具和 Stop-guard 的形式发布,无论模型是否调用它,都会生效)与 **recall**(记忆)。 + +## Guard 胜过散文 + +模型有可能漂移出的规则以散文形式存在;它 **绝不** 能违反的规则以 guards(确定性 shell 钩子)存在。guard 不会在上下文压缩后被遗忘。 + + + 把每一条可强制的不变式从 `CLAUDE.md` 迁到 guard;让散文保持稀薄。这是 Forge 设计中最重要的一条纪律。 + + +## 已核实的跨工具生成矩阵 + +Forge 为**九个工具**生成配置,并为 Roo Code 和 VS Code 提供一台 MCP 服务器。每一行都对照厂商文档核实过。 + +| 工具 | 原生目标 | Forge 如何生成 | +| ------------------ | ---------------------------------------------------------------- | --------------------------------------------------------------------- | +| **Claude Code** | `CLAUDE.md`(+ `.claude/rules/*.md`、`settings.json`) | 首行为 `@AGENTS.md` 的薄 `CLAUDE.md`;guards → settings | +| **Codex** | 原生 `AGENTS.md`(32 KiB 上限) | 根目录的规范 `AGENTS.md` **就是**源 | +| **Cursor** | `AGENTS.md` + `.cursor/rules/*.mdc` | 扁平规则用 `AGENTS.md`;需要作用域时用 `.mdc` | +| **Gemini** | `GEMINI.md`,或通过 `context.fileName` 选用 `AGENTS.md` | 写入 `.gemini/settings.json` 以避免第二份副本 | +| **Aider** | 通过 `.aider.conf.yml` 的 `read:` 读取 `CONVENTIONS.md` | 生成带 `read: AGENTS.md` 的 `.aider.conf.yml` | +| **Copilot** | 根 `AGENTS.md` + `.github/copilot-instructions.md` | 依赖根 `AGENTS.md`;可选的 `.github` 指针 | +| **Windsurf/Devin** | 自动发现的 `AGENTS.md`(上限 6k/12k 字符) | 根 `AGENTS.md` 保持在上限之下;区分 `.windsurf` 与 `.devin` | +| **Zed** | 包含 `AGENTS.md` 在内的一份优先级列表中的首个匹配 | 生成 `AGENTS.md`;doctor 会标出任何被遮蔽的旧文件 | +| **Continue** | `.continue/rules/*.md` + `.continue/mcpServers/*.yaml` | 生成一份规则文件外加 Forge MCP 服务器配置 | + +Roo Code 与 VS Code 通过 `forge init` 获得 Forge MCP 服务器 +(`.roo/mcp.json`、`.vscode/mcp.json`),而不是规则文件。 + + + **字符上限是真的。** Codex 会在 32 KiB 处截断,Windsurf 在 6k/12k 处截断。`forge sync` 会强制执行一个源大小预算,以免配置被悄悄截断。 + diff --git a/mintlify/zh-Hans/concepts/cross-session-memory.mdx b/mintlify/zh-Hans/concepts/cross-session-memory.mdx new file mode 100644 index 0000000..2eb0e0a --- /dev/null +++ b/mintlify/zh-Hans/concepts/cross-session-memory.mdx @@ -0,0 +1,73 @@ +--- +title: "跨会话记忆" +description: "会话锚定、完成关卡、handoff 快照与决策日志——用来终结会话失忆和部分完成的那一层。" +--- + +这一层要终结的两种失效模式:**部分完成**(代码变了,但依赖它的产物没跟上)和 **会话失忆**(下一次会话又要重新假设这一次已知的东西)。指令能提升正确行为的 _概率_;确定性钩子保证一个 _下限_。 + +## 会话锚定 + +在 `SessionStart`(`src/session.js`)时,Forge 会记录一次 `HEAD`、修剪一周前的会话产物,并注入一份新的定位信息: + + + + 从过往更正中挖出的 cortex 经验。 + + + 声明的目标,以便据此度量漂移。 + + + 上一次会话写下的有边界的 `.forge/state.md`。 + + + 最近的提交与未提交改动——作为证据,而非先验。 + + + +一个新会话基于证据、而非先验,来定位自己。 + +## 完成关卡 + +Stop 路径上唯一有权作答的 guard 是 `completion-gate.sh` +(`src/gate.js`)。它同步运行;挖掘经验的 `cortex.sh stop` 保持分离,永远不会阻塞。 + +变更集是**会话范围**的:提交者时间在会话开始之后的提交所涉及的文件,加上工作区的改动,再减去在 `SessionStart` 时快照的“脏文件”——因此已存在的编辑、分支切换和 `git pull` 永远不会被算到代理头上。 + + + 如果代码动了、却没有跟进文档或状态产物,该关卡会**拦下一次**,并以修复清单作为原因。其他情况一律放行,所有内部错误也放行(fail-open)。`FORGE_STOPGATE=0` 可关闭它。 + + +修复清单指向能把工作收尾的工具: + +```bash +forge docs sync # 扫过 diff,找出过期的文档提法 +forge handoff "" --next "" # 写下有边界的会话快照 +forge decide " — " # 记录一次选择,让下一次会话不再重新决定 +``` + +## Handoff 与决策 + +两种存储让知识跨会话延续: + +| 存储 | 语义 | +| --------------------- | ------------------------------------------------------------------------------------ | +| `.forge/state.md` | 有边界的**重写**(快照)——加载成本永远保持 `O(bound)`。 | +| `.forge/decisions.md` | 仅追加的**精简 ADR**(`D-####`),带一份机器可读的决策 ledger 副本。 | + +两者在写入时都拒绝密钥。`state.md` 会在每次会话开始时被重新注入; +`decisions.md` 会在重新决定过往会话已定的事之前先被读到。 + +```bash +forge handoff "" --next "" +forge decide " — " +forge decide # 在重新决策之前先读一读日志 +``` + +## diff 驱动的文档清扫 + +`forge docs sync` 回答这个由 diff 决定形状的问题:变更的标识符 +(来自新增 _与_ 删除行中的路径、定义与被调用符号)对每个文档产物做扫描 → UPDATED / STALE(带 file:line 命中)/ VERIFIED-UNAFFECTED,并记录原因。它是纯报告器;真正咬人的牙齿由完成关卡提供。 + + + `recall` 和 `cortex` 仅仅是文件与提示级别的记忆——**不是** 权重级学习。合并操作是一个可能产生幻觉的总结器,所以它保持建议性、人工可复核,并且不包含密钥。 + diff --git a/mintlify/zh-Hans/concepts/model-routing.mdx b/mintlify/zh-Hans/concepts/model-routing.mdx new file mode 100644 index 0000000..40b8fa6 --- /dev/null +++ b/mintlify/zh-Hans/concepts/model-routing.mdx @@ -0,0 +1,63 @@ +--- +title: "模型路由" +description: "一份确定性、可 diff 的评分表在分发之前挑选出能胜任的最便宜模型层——外加针对自托管 gateway 的安全兜底重映射。" +--- + +Forge 在分发**之前**为任务推荐能胜任的最便宜模型,依据是一份你可以在仓库里读到的确定性评分表(`src/model_tiers.json`)。与在代理内部于请求时刻做决定的 gateway 不同,路由决定在 git 中是可见且可 diff 的。 + +## 推荐一个 tier —— `forge route` + +```bash +forge route "" # 任务的最便宜可胜任模型 tier +forge route gateway # 生成 LiteLLM gateway 配置 +``` + +推荐依据是一个基于样本 k-NN 的数学计算,在一份标注库(英语 + Hinglish 行)上、以重叠相似度作为度量,并带一个置信度阈值——不是关键词查表。 + + + 从推荐的 `route.tier` 开始,只在外部校验者失败后升级,绝不预先升级。这样既压低支出,又不会在任务确实需要时限制能力。 + + +## 先意图,后 tier + +路由与意图识别(`src/intent.js`)共享同一套数学:一段提示通过同一个样本 k-NN 估计器映射到一个意图。注意二者使用不同的停用集——route 把泛用动词(`fix` / `add` / `build`)视为复杂度噪声,而这些动词恰是意图的信号。 + +## Tier 表 + +tier 表(`src/model_tiers.json`)按家族(haiku / sonnet / opus / fable)固定了 Anthropic 的公开模型 ID。文档里的价格通过文档检查与该文件对账,因此正文和表格不会漂移。 + +## 自托管 gateway 的重映射 + +自托管的 LiteLLM 或代理 gateway 会使用它自己的模型名称,所以直接把 stock ID 发过去会 404。当配置了非默认的 gateway base URL 时,Forge +(`src/gateway_model_map.js`)会**每个进程只**取一次 `GET /v1/models`,并把每个已宣告的 id 对每个 tier 的家族打分: + + + + 家族关键词(haiku / sonnet / opus / fable)必须匹配——它是硬闸。 + + + 在同家族内部,tier 名称 token 的 `setOverlap` 系数选出最佳匹配。 + + + 平局时,更接近规范名的 id 胜出。 + + + + + 重映射**仅**在解析出的 id 是 _stock_ ID 时才咨询 gateway——显式的 + `.forge/providers.json` 别名或 `ANTHROPIC_MODEL` 覆写永远不会被触及。它在没有 gateway、`/v1/models` 不可达或家族不匹配时安全退回到 stock ID,因此直连 `api.anthropic.com` 的用户是逐字节相同的。 + + +`forge doctor` 的 **gateway models** 行会打印解析出的 `tier → model` 映射以便核对。 + +## 提供方与成本 + +```bash +forge config # 展示 / 切换 / 添加提供方,设置默认模型 +forge cost # 真实的每日花销 +forge cost --stages # 实测的每阶段成本系数 +``` + + + `forge cost --stages` **仅报告已实测的阶段**——没有事件的阶段会显示 “no data”,绝不使用默认值。一个数字在被测量之前只是一个假设。 + diff --git a/mintlify/zh-Hans/concepts/pre-action-gate.mdx b/mintlify/zh-Hans/concepts/pre-action-gate.mdx new file mode 100644 index 0000000..b4220c9 --- /dev/null +++ b/mintlify/zh-Hans/concepts/pre-action-gate.mdx @@ -0,0 +1,86 @@ +--- +title: "行动前关卡" +description: "forge substrate 在模型编辑代码之前跑一趟有序的检查,并返回一次裁决——假设、路由、影响、范围、记忆与验证。" +--- + +**认知基座**——在模型编辑代码 _之前_ 运行的那一层。`forge +substrate ""`(以及 MCP 工具 `substrate_check`)运行一趟有序的检查,并返回一次裁决。它把各阶段——`preflight`、`route`、`atlas`、`impact`、`reuse`、`context`、`scope`、`lean`、`anchor`、`verify`——合成一份行动前契约,这些阶段也都能单独调用。 + +```mermaid +flowchart TD + RE["referenced entities"] --> INTAKE + subgraph INTAKE["intake"] + direction LR + PF["preflight · assumption gap"] --> RT["route · cheapest tier"] + end + INTAKE --> ANALYSIS + subgraph ANALYSIS["analysis"] + direction LR + AT["atlas · code graph"] --> IM["impact · blast radius"] --> PT["predict · failing tests"] --> RU["reuse · cache hit?"] + end + ANALYSIS --> SAFETY + subgraph SAFETY["safety + fit"] + direction LR + CX["context · completeness gate"] --> SC["scope · coupled files"] --> ME["memory · recall + lessons"] --> MN["minimality · lean footprint"] --> GA["goal-anchor · drift check"] + end + SAFETY --> VD["verdict"] +``` + +## 三个阶段 + + + + **preflight** 找出假设缺口——任务点名却在仓库里未定义的东西。**route** 挑出能胜任的最便宜模型 tier。 + + + **atlas** 读取代码图,**impact** 计算爆炸半径,**predict** 指出可能失败的测试,**reuse** 检查是否命中已验证的缓存。 + + + **context** 运行完整性关卡,**scope** 浮现耦合文件,**memory** 注入 recall + 经验,**minimality** 衡量精简足迹,**goal-anchor** 检查漂移。 + + + +## 爆炸半径 + +**爆炸半径**——一次编辑被预测会影响到的文件集,从代码图中读出。`forge impact` 计算它;管道会在模型触碰任何东西之前把它浮现出来。 + +```bash +forge impact verifyToken # 一个符号的预测受影响文件 +forge impact src/auth.js # ……或一个文件的 +``` + +## 默认建议性 + +裁决**默认是建议性的**——它报告,不阻断。设置 +`FORGE_ENFORCE=1` 可把最强信号变成硬阻断: + + + + preflight 找不到可执行意图——任务描述不足。 + + + 完整性关卡无法覆盖预测的编辑集。 + + + 受影响集超过默认约 25 个文件的阈值。 + + + +其他一切都保持为可被人工覆写的警告。 + + + 在 Claude Code 上,整个关卡通过 `UserPromptSubmit` 钩子在**每次提示自动**运行——对干净任务保持安静。`forge substrate "" --json` 给出可脚本化的机器可读裁决。 + + +## 运行它 + +```bash +forge substrate "Change verifyToken in src/auth.js to require length > 20; update tests" +forge substrate "" --json +``` + +如果裁决是 `ASK FIRST`,在编辑前先问它返回的 `assumption.questions` ——不要对一个描述不足的任务瞎猜。从推荐的 `route.tier` 开始,只在外部校验者失败后升级,绝不预先升级。 + + + 记忆阶段从携证 ledger 中读取。 + diff --git a/mintlify/zh-Hans/concepts/proof-carrying-memory.mdx b/mintlify/zh-Hans/concepts/proof-carrying-memory.mdx new file mode 100644 index 0000000..71316e7 --- /dev/null +++ b/mintlify/zh-Hans/concepts/proof-carrying-memory.mdx @@ -0,0 +1,97 @@ +--- +title: "携证记忆" +description: "每一条被存储的事实、经验或复用产物,都是一条自带证据的主张——只有当独立裁决者把其置信度抬到下限之上时才被信任。" +--- + +**携证记忆(PCM)**——每一条被存储的事实、经验或复用产物,都是一条自带证据的 _主张_。它只有在独立裁决者(测试、CI、人工接受/回退)把它的置信度抬到某个下限之上时才被信任。错误的经验会衰减出去,而不是固化下来。 + + + “携证记忆” 是我们对 **带证据引用、内容寻址记忆** 的称呼——主张以其内容哈希作为地址,并与背书它的裁决结果相互链接。“证明”指的是这条证据链加上置信度规则,**并不是形式化的、机器可校验的证明**;整条链路里没有定理证明器。 + + +## 一个存储,多个写入者 + +所有记忆子系统都汇聚到同一个存储。`recall`、`remember`/`brain`、`cortex` 经验、`reuse` 产物和死循环 `diagnose` 结果都会把内容寻址的主张写入 `.forge/ledger/`。 + +```mermaid +flowchart LR + subgraph EV["local events"] + direction TB + E1["recall / remember"] + E2["cortex lesson"] + E3["reuse mint"] + E4["diagnose"] + end + EV -->|"content-addressed claims"| LG["(.forge/ledger)"] + O["independent oracles · tests · CI · human accept/revert"] -->|"append evidence · move confidence"| LG + TM["teammate ledgers"] <-->|"git union-merge · conflict-free"| LG + LG --> RV["merged read view · recall list · lesson inject · brain index"] +``` + +## 为什么它能无冲突地收敛 + +因为一条主张的字节是 `(kind, body, scope)` 的纯函数,每个副本都会计算出相同的身份——因此队友的 ledger 通过纯 git 无冲突地并入。 + +机制上: + +- **证据与墓碑是仅追加的**、按哈希去重的日志。 +- **置信度(`val`)** 是衰减的 Beta 后验,只由裁决者推动。 +- **合并是 join-semilattice**——经过属性测试为可交换、可结合、幂等——因此 ledger 在任意顺序下都会收敛。 + + + `forge init` 会生成 ledger 所需的 union-merge `.gitattributes` 规则;`forge + ledger merge ` 会并入任意另一棵 ledger 树。完整决策记录在 ADR-0006(携证记忆)。 + + +## 只有裁决者能推动置信度——其他任何东西都不行 + +只有独立裁决者能推动一条记忆的置信度: + + + + 覆盖该主张的一个通过测试会提升它的置信度。 + + + 一条绿色流水线是该主张仍然成立的独立证据。 + + + 显式接受或一次回退是最强的信号。 + + + +不可验证的证据会被一个封闭的 `ORACLES` 表(`src/ledger.js`)拒绝。未经复核的知识会衰减向 _不确定_,而不是被删除——休眠主张会被保留以供审计,绝不会被悄无声息地清除。 + +## Ledger 命令面 + +```bash +forge ledger stats # 本仓库知道什么,按类别与信任等级列出 +forge ledger verify # 重新校验主张处于范式 +forge ledger show # 一条主张及其证据链 +forge ledger blame # 谁写下的、每一次裁决结果、按作者划分的信任度 +forge ledger query "" # 按相关性检索主张 +forge ledger ratify # 人工接受 +forge ledger retract # 给一条主张打上墓碑 +forge ledger merge # 无冲突并入队友的 ledger +forge ledger import # 把旧存储桥接到 ledger 中 +``` + +加上 `--personal` 使用每用户的 ledger。 + +## reuse 缓存也是携证的 + +`forge reuse` 是一个携证的代码缓存。一个已生成的产物只有在其证据仍然成立时才会被再次提供——置信度在下限之上 **并且** 它在 atlas 中的依赖仍然解析得到。否则它会回退到生成路径,并在返回途中打上一条新的主张。 + +```mermaid +flowchart LR + SP["spec"] --> FP["fingerprint · MinHash + LSH"] + FP --> LD["match ladder · exact to near to adapt to miss"] + LD --> GT{"confidence >= floor AND deps resolve?"} + GT -->|"yes"| SV["serve · proof holds"] + GT -->|"miss"| GN["generate"] + GN -->|"mint claim"| MT["(.forge/ledger)"] +``` + + + MinHash 的近邻匹配在非常短的规约上偏弱。可选的 embeddings 后端 + (`FORGE_EMBED`)能改善这一点;MinHash 依然是零依赖的默认。 + diff --git a/mintlify/zh-Hans/concepts/verification-gates.mdx b/mintlify/zh-Hans/concepts/verification-gates.mdx new file mode 100644 index 0000000..5187793 --- /dev/null +++ b/mintlify/zh-Hans/concepts/verification-gates.mdx @@ -0,0 +1,83 @@ +--- +title: "验证关卡" +description: "独立验证、幻觉符号标记、规约即契约与技能关卡——你能实际运行的检查,它们能减少但从不能认证正确性。" +--- + +没有可以真正跑一遍的检查,就不算 “完成”——一个测试、一个构建退出码、一张截图。Forge 的验证关卡各自多接住一次。设每任务漏率为 `1 − p`,关卡拦截率为 `c`,则静默漏失下降到 `(1 − p)(1 − c)`,而这里每一道关卡都多贡献一个 `c`。 + + + **验证是减少,不是认证。** Crew 校验者和幻觉符号标记能降低评审负担;它们并不证明代码正确。测试和人工纠正永远胜出。 + + +## 独立验证 —— `forge verify` + +一道独立关卡:它会跑仓库真实的测试、标出幻觉符号,并检查溯源。 + +```bash +forge verify # 测试 + 幻觉符号 + 溯源 +forge verify --deep # 多视角共识——多个独立检查必须一致 +``` + + + `--deep`(v0.19+)升级为多视角共识:变更必须通过多个独立的验证视角,而不只是一个。 + + +## 幻觉符号标记 —— `forge atlas has` + +`forge atlas has ` 是幻觉检查:如果模型调用了不在代码图里的符号,该关卡会把它标出来。 + +```bash +forge atlas build # 索引本仓库的符号 → .forge/atlas.json +forge atlas has useAuth # “not found” = 很可能是幻觉 +``` + +atlas 有意做成纯 JSON——Codex、Cursor、Gemini 和 Aider 都可以通过 CLI 或直接的 `jq` 消费 `.forge/atlas.json`,不需要依赖 MCP。 + +## 规约即契约 —— `forge spec` + +把行为固定到一份规约上,并检测与之的漂移: + +```bash +forge spec init # 生成一份 OpenSpec 契约 +forge spec lock # 把当前规约锁定为契约 +forge spec check # 报告与锁定契约的漂移 +``` + +## 技能关卡 —— `forge scan` + +在安装 skill 或 MCP 服务器之前,审查它是否有注入、RCE 或数据外泄风险: + +```bash +forge scan +``` + + + 扫描通过 **不是安全认证。** 内置启发式只能识别已知的攻击形态(critical)和少量高严重度的模式;通过意味着 _“未检测到 critical 特征”_,而不是 _“可以放心安装”_。永远要自己审阅源码、权限、包溯源和网络行为。**high** 严重度的发现即便不硬阻断,也不会被标记为安全。外部扫描器是可选的,除非你启用它,否则不会发起任何网络调用。 + + +## 加固 —— `forge harden` + +接线让密钥和不安全的变更进不了仓库的安全控制: + +```bash +forge harden # gitleaks pre-commit + 沙箱设置 +``` + +## commit 级别关卡 —— `forge precommit` + + + `forge precommit`(v0.19+)是一道 commit 级别的关卡——它在 commit 时运行验证下限,让部分或未验证的工作在落地前被拦下。 + + +## UI 检查 —— `forge uicheck` + +确定性 UI 检查,前三个视角不使用 LLM 也不使用截图: + +```bash +forge uicheck contrast # WCAG 对比度 +forge uicheck fingerprint # 确定性设计指纹 +forge uicheck design # slop 距离 + 合规关卡 +forge uicheck visual # 基于 Playwright 的渲染检查(可选层) +``` + +搭配 `forge taste` 选定一个视觉方向(brutalist、corporate、editorial、minimalist、playful),并参数化 `design` 关卡的阈值。 diff --git a/mintlify/zh-Hans/guides/radar-deps.mdx b/mintlify/zh-Hans/guides/radar-deps.mdx new file mode 100644 index 0000000..d15b3e4 --- /dev/null +++ b/mintlify/zh-Hans/guides/radar-deps.mdx @@ -0,0 +1,56 @@ +--- +title: "用 radar 保持依赖时效性" +description: "forge radar 把你的依赖按时效性分组为环,让陈旧或漂移的依赖在造成问题之前显形。" +--- + + + `forge radar` 正在 v0.19 系列中登陆。本指南描述它如何契合既有的依赖时效性纪律;运行 `forge --help` 以确认你安装的版本中是否可用。 + + +Forge 的工程规则之一是:_在添加一个依赖之前,从实时来源核实当前的最佳选项,并优先使用项目已经在用的。_ `forge radar` 让你的依赖的当下状态变得可见,好让这条规则背后有数据支撑。 + +## 思路:时效性环 + +`forge radar` 把项目的依赖按各自的时效性分入同心的**时效性环**——从中心的最新版本,向外到边缘的陈旧或漂移。读这些环是回答“我们让什么漂了?”的一种快速方式,不必手工审计每一个包。 + +```bash +forge radar +``` + +## 依赖清单从哪里来 + +Radar 依赖的清单读取逻辑,与驱动 `forge stack` 的一致——后者从依赖清单文件中检测仓库的真实技术栈: + +```bash +forge stack # 语言、框架、包管理器、真实的测试命令 +``` + +因为检测是数据驱动、且在各生态系统间安全兜底(`package.json`、 +`pyproject.toml`、`go.mod`、`Cargo.toml`、`Gemfile`、`composer.json`、`pom.xml` / +`build.gradle`、`*.csproj`),radar 可以对 `stack` 所理解的同一批清单文件推理其时效性。 + +## 在日常工作中使用它 + + + + 在添加或升级依赖之前,先跑 `forge radar` 看看哪些依赖已经在漂。 + + + 如果一个内圈里已经有一个胜任且当前的依赖,就复用它,而不是再引入一个——最贴合需求的最小改动胜出。 + + + 当你真的升级或替换了一个依赖,记录原因: + ```bash + forge decide "bump to — " + ``` + 这样未来的会话读得到这个选择,而不会重新走一遍。 + + + + + Radar 报告时效性;它不会替你升级。把它的环视为给人工决策的建议性输入——并在把变更算作 “完成” 之前,用仓库真实的测试(`forge verify`)核实任何一次升级。 + + + + 一次依赖升级之后,跑一遍 Quality 关卡——`forge verify` 和 `forge precommit`。 + diff --git a/mintlify/zh-Hans/guides/team-memory.mdx b/mintlify/zh-Hans/guides/team-memory.mdx new file mode 100644 index 0000000..ab63111 --- /dev/null +++ b/mintlify/zh-Hans/guides/team-memory.mdx @@ -0,0 +1,66 @@ +--- +title: "用 ledger 做团队记忆" +description: "通过纯 git 无冲突地并入队友的 ledger——没有服务器,没有同步服务,只是一些按任意顺序都能收敛的文件。" +--- + +基座学到的一切——cortex 经验、`forge remember` 事实、已验证的复用产物——都作为内容寻址的主张落到一个 git 原生的 ledger(`.forge/ledger/`)里,它天生就为无冲突合并而设计。没有服务器,也没有同步服务;只是 git 里的文件。 + +## 三条命令搞定团队记忆 + + + + ```bash + forge init + ``` + 这会生成 ledger 所需的 `.gitattributes` union-merge 规则,以及其他配置。 + + + 你正常工作时,cortex 经验与 `forge remember` 事实会把主张镜像进 ledger——不需要额外执行任何命令。 + + + ```bash + git pull && forge ledger merge + ``` + 任意顺序——合并是无冲突的。 + + + +## 为什么它不会冲突 + +一条主张的字节是 `(kind, body, scope)` 的纯函数,所以每个副本对相同的知识都会算出相同的身份。合并是一个 join-semilattice——经过属性测试为可交换、可结合、幂等——因此两位队友的 ledger 无论谁先同步都会收敛到相同的状态。 + +```mermaid +flowchart LR + A["your ledger"] <-->|"git union-merge · conflict-free"| B["teammate ledger"] + A --> M["merged read view"] + B --> M + M --> R["recall list · lesson inject · brain index"] +``` + + + 相同的知识在两处独立生成,会收敛为**一条**主张,并在其溯源中保留每一位作者。 + + +## 信任与溯源 + +置信度只由独立裁决者推动——测试、CI、人工接受/回退——所以并入队友的 ledger 并不是盲目相信他们的笔记;而是并入他们的 _证据_。 + +```bash +forge ledger blame # 谁写下的主张、每一次裁决结果、按作者划分的信任度 +forge ledger stats # 合并后的视图,按类别与信任等级列出 +forge ledger verify # 确认每一条主张处于范式 +``` + +## 全团队的复用 + +一旦队友已验证的代码进入合并后的 ledger,你就可以带着它的证明来复用: + +```bash +forge reuse query "" +``` + +一次命中会指向可运行、有测试确认的代码,以及能证明它的 `forge ledger blame` ——复用它,而不是重新生成。 + + + 休眠主张会被保留以供审计,绝不删除;未复核的知识会衰减向 _不确定_,而不是被删除。ledger 是一条证据链,不是一个能悄悄丢失的缓存。 + diff --git a/mintlify/zh-Hans/guides/zero-config-onboarding.mdx b/mintlify/zh-Hans/guides/zero-config-onboarding.mdx new file mode 100644 index 0000000..7a177d0 --- /dev/null +++ b/mintlify/zh-Hans/guides/zero-config-onboarding.mdx @@ -0,0 +1,81 @@ +--- +title: "有引导、低配置的接入" +description: "五分钟到可用:装一次、每个仓库配一次、做一次任务,并在第二天开始看到 ledger 带来回报——是有引导、低配置,而不是零操作。" +--- + +Forge 的目标是**有引导、低配置的接入**——一个新仓库通常在大约五分钟内就能进入可用状态。装一次、每个仓库配一次、做一次任务,ledger 就会在第二天开始带来回报。(它是低配置的,不是零配置:你仍然要安装 CLI、在每个仓库里跑 `forge init`,而且部分路径依赖 Bash、Git 和 `jq`。) + +```mermaid +flowchart TD + I["forge init"] --> Cfg["every tool configured from one source"] + Cfg --> Work["you work as usual"] + Work --> Gate["substrate checks each task · ask first? · which model? · what breaks?"] + Gate --> Edit["agent edits, with guardrails"] + Edit --> Learn["cortex learns from corrections"] + Learn -.->|next task is smarter| Work +``` + +## 1. 安装(一次) + +推荐路径不需要 token 也不需要克隆: + + + +```bash Plugin +/plugin marketplace add CodeWithJuber/forgekit +/plugin install forgekit +``` + +```bash CLI +npm install -g @codewithjuber/forgekit +``` + + + +```bash +forge doctor # 一切都绿了吗? +``` + +## 2. 配置一个仓库(每个仓库一次) + +```bash +cd ~/your-project +forge init # 生成 AGENTS.md、CLAUDE.md、.gemini/settings.json、.aider.conf.yml…… +``` + +现在 Claude Code、Codex、Cursor、Gemini、Aider、Copilot、Windsurf、Zed 和 Continue 都从各自的原生文件里读**同一套**规则。之后要改规则,编辑 +`source/rules.json`(或在仓库里放一份 `.forge/rules.json`),然后跑 `forge sync`。 + +## 3. 使用认知基座 + +```bash +forge substrate "" # 一次跑完 ask/route/impact/scope/reuse/context/memory/verify +forge substrate "" --json +forge impact # 单独跑爆炸半径 +``` + +如果 `forge substrate` 返回 `ASK FIRST`,在编辑前先问它返回的那些问题。 + +## 4. 用一下附加功能 + +```bash +forge atlas build # 索引本仓库的符号 → .forge/atlas.json +forge atlas query useAuth # 它在哪里定义? +forge atlas has useAuth # 它存在吗?“not found” = 很可能是幻觉 +forge recall add "db port" "Postgres is on 5433 here, not 5432" +forge catalog # 一切内容的 Start-Here 索引 +``` + +## 5. 第二天:ledger 开始学习 + +基座在第一天学到的一切——cortex 经验、被记住的事实、已验证的代码——都以主张形式落到了 `.forge/ledger/`。 + +```bash +forge ledger stats # 本仓库知道什么,按类别与信任等级列出 +forge ledger blame # 谁写下的主张、每一次裁决结果 +forge reuse query "" # 你已经拥有的、已验证的代码 +``` + + + 下一步:通过纯 git 无冲突地并入队友的 ledger。 + diff --git a/mintlify/zh-Hans/installation.mdx b/mintlify/zh-Hans/installation.mdx new file mode 100644 index 0000000..a413e2a --- /dev/null +++ b/mintlify/zh-Hans/installation.mdx @@ -0,0 +1,98 @@ +--- +title: "安装" +description: "一棵树上的三扇前门:插件市场、npm 全局安装,以及免注册表的 github: 安装——外加贡献者的 symlink 开发环境。" +--- + +Forge 遵循**一棵树,三扇前门**的设计:插件清单、加固过的安装器和 npm 二进制都引用同一棵 `global/` + `source/` 树。选择适合你工具的通道即可。 + +## 选择一个通道 + + + + 适用于 Claude Code 和 Codex。护栏自动接线;无需合并任何东西。 + + + 适用于任何工具。从公开 npm registry 安装的 `forge` CLI。 + + + 不需要 registry——直接从仓库安装。 + + + 克隆 + `npm link`,或运行 `bash install.sh` 使用 symlink 方案。 + + + +## 系统要求 + +- **Node.js >= 20** +- **零运行时依赖**——一切都用 Node 内置模块。可选层(`FORGE_EMBED` 嵌入、`uicheck visual` 所需的 Playwright)是可选的,不引入必需依赖。 + +## 插件市场 + +给 Claude Code 和 Codex 用的推荐路径,不需要 token 也不需要克隆: + +```bash +/plugin marketplace add CodeWithJuber/forgekit +/plugin install forgekit +``` + +插件通过 `${CLAUDE_PROJECT_DIR}` 接线护栏,让行动前关卡和完成关卡在后台自动生效。 + +## npm 全局安装 + +任何工具都能用,来自公开 npm: + +```bash +npm install -g @codewithjuber/forgekit +forge doctor # 一切都绿了吗? +``` + +## 免注册表的 github: 安装 + +```bash +npm install -g github:CodeWithJuber/forgekit +``` + +## 贡献者 / 本地开发 + + + +```bash npm link +git clone https://github.com/CodeWithJuber/forgekit.git +cd forgekit +npm link +``` + +```bash install.sh (symlink setup) +git clone https://github.com/CodeWithJuber/forgekit.git +cd forgekit +bash install.sh +``` + + + +安装器是加固过的:幂等、基于 symlink、有备份、且不使用 `curl | sh`。 + +## 验证 + +不论你走了哪个通道,都要确认安装成功: + +```bash +forge doctor # 工具、护栏、MCP 授权、配置漂移、更新状态 +``` + + + `forge doctor` 还会对 git checkout 用户显示一条不烦人的“落后上游 N 个 commit”提示。设置 `FORGE_NO_UPDATE_CHECK=1` 可将其静默。所有路径都是 fail-open——离线或 detached HEAD 会报告 “unknown”,绝不会报错。 + + +## 保持 Forge 最新 + +```bash +forge update --check # 报告是否有更新可用 +forge update # 应用更新(git checkout 或 npm/copy 安装) +forge update --to # 锁定或回退到特定版本 +``` + + + 前往快速开始,运行 `forge init` 与第一次基座检查。 + diff --git a/mintlify/zh-Hans/introduction.mdx b/mintlify/zh-Hans/introduction.mdx new file mode 100644 index 0000000..7f84f63 --- /dev/null +++ b/mintlify/zh-Hans/introduction.mdx @@ -0,0 +1,103 @@ +--- +title: "简介" +description: "Forge 是每个无状态模型都缺少的认知基座——记忆、预见与护栏——以原生配置形式交付给每一个 AI 编码代理。" +--- + +**给每个 AI 编码代理一个大脑。** 大语言模型是无状态的：只有一个上下文窗口，每次调用都会清空。它对你的团队学到的东西没有记忆，对一次编辑会打破什么没有预见，也没有强制执行的护栏。Forge +（`@codewithjuber/forgekit`）就是这一层**认知基座**——在模型编辑代码 _之前_ 运行的那一层，提供带证据引用、内容寻址的记忆（我们称之为 +“携证记忆”）、启发式的影响预见与强制护栏——并配备一个**跨工具配置编译器**，把这个大脑一次性以原生配置的形式交付给每个工具。Claude +Code 是经过最深入测试的集成；其余工具也会获得原生配置和 MCP 工具，只是实际验证较少。 + + + + 跨会话与跨队友持久保留的携证记忆。每一条经验、事实与已验证的复用，都是一条自带证据的主张。 + + + 一次编辑的爆炸半径——从代码图中读出的、被预测会被触及的文件集，包括你从未点名的耦合文件。 + + + 确定性的钩子强制执行模型绝不能违反的规则。它们能挺过一次上下文压缩，而写在配置文件里的散文规则做不到。 + + + +## 问题 + +大语言模型是无状态的——一个上下文窗口，每次调用都会清空。 + +- 它**没有记忆**记住你的团队已经学到了什么。 +- 它**没有预见**知道一次编辑会打破什么。 +- 它**没有强制护栏**——散文式的规则在一次压缩后就会被遗忘。 + +而且每个工具都想要自己的配置文件（`CLAUDE.md`、`AGENTS.md`、`.cursor/rules`、 +`GEMINI.md`、MCP……）。Forge 就是那一层认知基座，补上这三样缺失的东西，同时也是把它从一份源交付到每个工具中的编译器。 + +## 核心论点 + +模型在两次调用之间无法从你的代码库学习：它的权重是冻结的，工作记忆在每次响应后都会被清空。记忆、预见和自检不能靠提示词灌进去——必须从 _外部_ 提供。这一外部层就是认知基座。形式上，推理是一个固定函数 +`y = f(x)`，调用之间没有状态；Forge 就是那个状态。 + + + + 在唯一的规范源里写下你的规则和基座默认值 + （`source/rules.json`、`source/substrate.json`、`source/mcp.json`）。 + + + `forge sync` 把这份源编译成每个工具的原生配置——九个 AI 编码工具加上 MCP——带内容哈希头，因此漂移可被检测，重新运行是无操作。 + + + `forge substrate ""` 运行一次确定性的行动前流程：假设、路由、复用、上下文、爆炸半径、范围与目标锚点。 + + + 只有独立的裁决者——测试、CI、人工的接受/回退——才能推动一条记忆的置信度，因此错误的经验会衰减出去，而不是固化下来。 + + + +## 你能得到什么 + +- **跨会话、跨队友都持久的记忆。** 每一条经验、事实与已验证的复用都是 + _携证记忆（PCM）_ ——我们对带证据引用、内容寻址记忆的称呼：一条带有其证据引用的主张，只有当独立裁决者把它的置信度抬升到某个下限之上时才被信任。“证明”指的是这条证据链，不是形式化的证明。 +- **在打破东西之前预见。** 问“修改 `verifyToken` 会打破什么？”，就能从代码图中拿到爆炸半径，包括你从未点名的耦合文件。 +- **无法被遗忘的护栏。** 确定性钩子强制执行受保护路径、成本预算和死循环检测——它们能挺过上下文压缩。 +- **端到端把工作做完。** 一次会话内只触发一次的完成关卡会拦下这样一种情况：代码动了，但文档或状态产物没跟上——并把修复清单作为答复给出。 +- **一份配置服务九个工具。** 规则只写一次；Forge 会生成每个工具的原生配置，外加给 Roo 和 VS Code 的 MCP。零运行时依赖——一个 Node CLI、纯文件放在 git 里，没有服务器。 + +## Forge 给哪些工具喂配置？ + +Forge 为**九个工具**生成配置，另外为 Roo Code 和 VS Code 提供一台 MCP 服务器： +Claude Code、Codex、Cursor、Gemini、Aider、Copilot、Windsurf/Devin、Zed 和 Continue。 +每个工具都从各自的原生文件里读取同一份规则。 + +## 诚实的边界 + +Forge 到处都会声明自己的上限。 + + + Forge **减少而非消除**规则漂移。它是一层透明性和可靠性的加固，不是测试、评审或判断力的替代品。 + + +- **护栏只能强制执行能够表达为钩子的东西**（路径、格式、diff 大小、预算）。语义规则（“偏好函数式”）依然是散文形式，有时会被忽略。 +- **验证是减少，不是认证。** Crew 校验者和幻觉符号标记能降低评审负担；它们并不证明代码正确。 +- **没有权重级学习。** `recall` / `cortex` 仅仅是文件与提示级别的记忆——没有强化学习，没有微调。 +- **影响图是基于正则的近似**——保守，而不是可靠的调用图。 +- **测试和人工纠正永远胜出。** + + + Forge 目前处于 **beta**。核心（`init`、`sync`、`substrate`、`impact`、`ledger`、护栏）已经测试过并在日常使用；部分参数可能在 `1.0` 之前发生变化。 + + +## 下一步 + + + + 安装、运行 `forge init`,并让你的第一个任务过一遍基座。 + + + 四层编译器、携证记忆与行动前关卡。 + + + 每一条命令,按 Core、Memory、Substrate、Quality 和 Config 分组。 + + + 通过纯 git 无冲突地并入队友的 ledger。 + + diff --git a/mintlify/zh-Hans/quickstart.mdx b/mintlify/zh-Hans/quickstart.mdx new file mode 100644 index 0000000..2e1f055 --- /dev/null +++ b/mintlify/zh-Hans/quickstart.mdx @@ -0,0 +1,97 @@ +--- +title: "快速开始" +description: "安装 Forge,从同一份源生成每个工具的配置,并运行你的第一次行动前关卡——大约 60 秒。" +--- + +从零到一个配置好的仓库并跑通第一次基座检查,大约需要一分钟。 + +## 1. 安装 + + + +```bash Plugin (Claude Code / Codex) +/plugin marketplace add CodeWithJuber/forgekit +/plugin install forgekit +``` + +```bash npm (any tool) +npm install -g @codewithjuber/forgekit +``` + +```bash No registry +npm install -g github:CodeWithJuber/forgekit +``` + + + +对于 Claude Code 和 Codex,推荐走插件通道——护栏会自动接线,不需要合并任何东西。完整通道矩阵(包括开发者的 symlink 方案)见 [安装](/zh-Hans/installation)。 + +## 2. 配置一个仓库 + + + + ```bash + cd ~/your-project + forge init + ``` + 这会生成 `AGENTS.md`、`CLAUDE.md`、`.gemini/settings.json`、`.aider.conf.yml` 等——外加 ledger 所需的 `.gitattributes` union-merge 规则。现在 Claude Code、Codex、Cursor、Gemini、Aider、Copilot、Windsurf、Zed 和 Continue 都从各自的原生文件里读取**同一套**规则。 + + + ```bash + forge doctor + ``` + 对已安装工具、护栏、MCP 授权和配置漂移的通过/失败检查。 + + + 编辑 `source/rules.json`(或在仓库里放一份 `.forge/rules.json`),然后重新编译: + ```bash + forge sync + ``` + `sync` 是幂等的——只会重写发生变化的部分。 + + + +## 3. 运行行动前关卡 + +基座是在模型编辑代码 _之前_ 运行的那一层。一条命令就能跑完整个关卡: + +```bash +forge substrate "Change verifyToken in src/auth.js to require length > 20; update tests" +# → 假设裁决 · 能胜任的最便宜模型 · 预测的爆炸半径 +# (包括你未点名的文件) · 范围聚类 · 验证清单 +``` + + + 在 Claude Code 上,基座会通过 `UserPromptSubmit` 钩子**在每次提示自动**运行——仅作建议,对干净的任务保持安静。其他每个工具则会获得一条原生配置规则,外加 19 个可自行调用的 MCP 工具。 + + +如果 `forge substrate` 返回 `ASK FIRST`,在编辑之前先问它返回的那些问题。在任何有变更的改动之前,先读一读预测受影响的文件——爆炸半径。 + +```bash +forge substrate "" --json # 机器可读的裁决 +forge impact # 单独跑爆炸半径 +``` + +## 4. 探索附加功能 + +```bash +forge atlas build # 索引本仓库的符号 → .forge/atlas.json +forge atlas query useAuth # 它在哪里定义?(比 grep + 阅读更便宜) +forge atlas has useAuth # 它存在吗?“not found” = 很可能是幻觉 +forge recall add "db port" "Postgres is on 5433 here, not 5432" +forge catalog # 一切内容的 Start-Here 索引 +``` + +## 5. 第二天:ledger 开始学习 + +基座在第一天学到的一切,都以主张形式落到了 `.forge/ledger/`。这就是携证记忆——从现在开始它会带来回报: + +```bash +forge ledger stats # 本仓库知道什么,按类别与信任等级列出 +forge ledger blame # 谁写下的主张,每一次裁决结果 +forge reuse query "" # 你已经拥有的、已验证的代码 +``` + + + 阅读行动前关卡如何把各阶段合成一次裁决。 +